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PNIMALICN 2.05202. teapasesanacasatoetatieateeaateastaedap a attr. Goiaiiente naaiersacsase bun ouaiess 382 
DIMI CAC sais cnt veitecestrncas Pista denccatcbuseden sieaecnatentiehcgsiagedentelisiliviatslenadiefartveniaielnnstined? 383 
DIA COMM! ats sesso esti sep seg den stat entven cates: datadeutehivatyedsds leasentgesttenenaiatedettenatestiatensden’ 383 


PNIMGONVOl le siese ee he ae te tae ee a 384 


Linux Complete Command Reference 


PINITGEOP ad etivertrentecess eel citaawetee tiie Devearedtrte de vteusttadeniaee ea nvtanet aor tnennead 385 
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POMS Ol oo: cers aciantnieiilaannnnaniriadanninnisiinccnnnniicdecna 394 
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PMMCOTIES 2555 soe 8 aesactete, Pies diecedh te Bcgeteschaie arate otdeneias heat derdtiniere nm ieeecinndiieates 396 
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PPIX a sesitecs fcenceeched agtnrs brcdeecbevstea tints ca ened nag nave td ante eaeyenaae? 408 
PDITINOMIciini aos iaecceyestescntscuasdetrsatsansicsenntniecss feshtun ona danevideatgeateesetsdenadardanershsnave 409 
PDIVINESC 5 Posts 2ncs foseucetesttecseadensdenscaesebsdsteastons ne fogaeehqnulnanteaiebipatees cisdenndshgenspepantied 409 
DDIM Pls. ccnnsrszatedsttenstelevet.aststnisecabivanarnderdeicastteauvelacsfetsaptenetasthedatadevinstyareye celts 410 
DDIM QUIN esekiscatehe cxitecsasecctecenvadenstatiesavesteatstniensdeeiehty iiprdensdensuiajenttentiiataieutead 411 
PPMGUAN tall si wesie hdc des deuscasdiotbubwnidtauhobddnaiainage bude 412 


PPINIGV GG ceseecsce cacy Seti Mis ceaid ea ctevee ce wacenauegays ceaucesn cutvcswnea rece stevie nvadi decane gaurantee 412 


Introduction 


DPMrelief s.ncncaiakecanee 
Zach ao eC ee ee la 413 
dl a eG ag 413 
il oa ena ar 414 
HU cua ncn 414 
ei 416 
Ue ie er cee 416 
i 417 
SHIGE aaah ne esa 418 
ee a ee 419 
eee ee es 420 
eee eee ee es 421 
ee ee 421 
ee ee 422 
ee ee eo ee 422 
Seniel peace abcess ie ede Sl 423 
eee ee 424 
ee ee 424 
Score gs ee 425 
ee ee ee 425 
ee 426 
eg ee es 427 
cae eee iio Redes eae eee 427 
ii ees ea aca ee 428 
eg ee ee 428 
ee 429 
ee ey es 430 
a peared cre ae eae ae 433 
i ee ee 433 
ee ee 434 
Ses rcs cae eee ai 435 
a 436 
a aA eee aac ee eR eee eee 436 
Oe eg aes ae ee eee eee 437 
Se a eee 437 
bat ee ee ge ni ae ae ae 438 
Se ee ee 439 
a rs 439 
Ia eRe AC a re ee Sg aa a Bas 440 
chen uta aoe (pei atbee ag Seca pUR eT ap 441 
eae eee ee aoe epee tee 443 
AS Neg age ae ek east ge 445 
ee ee et 446 
ee ee 447 
seep ecest cat Sonata ees tid Setacacseneh oes eats ae a a 449 


TOI St sic Me coo eitie ees 
date bi vad daaae bent aeuatigd sue vagy ce Shaves ainda teoree agin anuaed 451 


xii 


Linux Complete C ommand Reference 


PECONT Oc, oh2sc arate eakarea ts eared vs encvess vias wehus tas eevee taeeatievds cura aberrant: 454 
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LOG senescence ease cree eetecat ete whee cepeemig toa tertile ee arene a: 458 
PLOGUIN, «aces tepee tie tesevhaees etree eae een coer toceet ek csrat, ccvaa eee geea tn tevave lies eaten tees 460 
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TSE POSES itisti seiner dsivastated aatenaiient ho ntitaaasihat mained 539 
TSO saci sesh ovbet vanes sane canes chguat avereeavatinet inn dustwavigastyanchdt sasdbaatts daedenaaabemeanumeneees 542 
16 (a ere Renee rereeerere reer terenecreritrcce tere verereritertre reer rrereetr pert rete reer terererrrcer ar 542 
(XE20Cdl io chs dkadnieegacnd oaaeth Gand agen banin aretha aden aeceo dis 558 
[lei diaes savecvsdacnce t@tairdarastetasateesar othe Shier ae akin bade dei tawe aa 558 
LIN EXPAN G si cess eceetinn pasties aaeelcdnerasuteunvih bare bean ni aes 559 
UDG) scssessenseucesegacs seat bachadsvecatstescvenensueeeducede cutsenadesieacedtantyd Sediasnuczgecite ad duanieniedées 560 
UD SV AM feces sscsstchecs. Shas hasiess Rcosszadieeavas th bad rashiethevaees do ohedttasteasi sedate 560 
UPC ALC seosssts a deasees Wi csassiders ches ga tea cea neatakis east cates eed tna ates sonentae nate 561 
UIPUIMG! sc. ccssssetet tial aa hade Animanuaumoamannadundnniinduaatsates 562 
USEWI | Sta. sssecencovsdeacresessiesecu ternatstedessseztbnagsraedisaattdetiaatehismaesnticienn Stetraanyees 563 
WUC sccsscschsceceatgatecesechzade avecia eaustebepaniad¥ssadete darsabseduegcgecegutacpuecStaueddgesadeds dh sate sabentics 563 
UUM COGDE fr e-2.5 aehestecsdieoscetedars abt, guetetesedioctasecds toveetatanstibezci esaztedatitan ieee tans 565 
USCA a ccaasssacasae cds ccupgacSiuashcdge te dssubeaa essen sbaggacacdteg’geduh sedosusgeadescusivauacadydededesddnasbdues 566 
UUM As oge roveh cocataae cocbanapawegadagiducessabiacaaggacdad aida sued aadeeddguse cn ggehdaagandabaenacgaudageeisbaskiduan 569 
UUM QE ccs shacduasctac ech ousaieadiecvaatuedscues te sucbinacnseqaoeedie ties @eiaditedh cabigbiegecadvie dduabie abies 572 
Wi sceslconstes seasactossctrscates seas abantasaaehagacsaiets Mtaescadece atta sa nebta et iaist saapte a Phdaacesbessestaasis 573 
Well tscsoisscenet seas seecidehtess ih canea.MeadazaeNiavia scat: hth dteasdagaeteay ans neabnes SM aves 574 
WCE as ESR h asda cit sue ucubap a dua g2ulivaautustnias cab denndahtapuyagussdutin date Maetuseis pinadeeadcestedebegeduaaduns 574 
WINERENS oss c.facccesetecest Succ duadacet tebe ot otecadasutesohsecedaavne savetscabscadeta tte hceeaeerdats lanes 575 
WLC et ce5, Satta. Sscater testa tatsacastes Mea acatinndhettetenatiaat eee set tue tue eiee teat tat 576 
MUD OUT ct, tea fish ontnadewatastra asain mani saosin abtiarir dein dae 577 
MTL POH COM Dish z. tse csxsteedearazetixea tatear areal d dacautrwdupttraa cabudeaendig dtenedaeens 585 
MORGS 2 ef ssitesets tan dutesebncebecntarstedend Mabesenanateaedettasattbvagathtatadcsfeatyasaitlerstoaterasehatecets dant 586 
MOE Mss cttees uted tans ease cots oth ca aati ste az tak. nas. anta aes aee tena cade tea cata 587 
MOMEOPDIM.tites.dcAcer tere crcideadhe sate dee deasdvadeseieatseerasdensdepeatiestss dusdensuasdearadecs 592 
yO | 0 SPE pees gPNP Rt Re-enter a eee ee 592 
MELO CS pesos he Ban awe beak es ue Sa aati Ri aa tatadde tee bavadua tutdess tees cans ccetenee seers 593 
NCP DO ANC 2 5 seandececdee.aeshdizsten, crareasseSeasdeabbver Biyedtiedsaedesnae cbt antdusdoraeebeaaenstocs 595 
MEOM SO O52 2. 2ach sca caetcbs Sasttaxdagebacees catbadabvsse tates satu dutindsesoneachens dots deuesuthoaneafaaadens does 597 
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MIM eoics os tea ont cese ae eins Av weenie ee vas ees 599 
KA PVINTO vrs. nent ee ale eae tint entoret ati narmeren 614 
X1BO ACCA crerracieic cate ciea ered ete en Re 614 
XF86 MonOttattust comnanienatee ennai 624 
XE86° SVG Aes ueus aha ana hana ea ae 627 
XE8OVGAIO rns pee aden ieee eRe eRe 631 
HI SOCONTI coe, esrhs caret ceaere i ae Teeek eT ree de eenee 633 
MiGhse cones? Roche tact eet saee ah eee astnc es bade en eee 633 
KERB Gisrtcsiert. cau nr nea mantinacdedhadcnaacdiadtnandimie eee 636 
WS eink el ae ester atecastettctes te anddavidetietandiebanwhenaee 641 
MMOS isc secosuecia dh ivncaa thee fecitteues facts beds tastreteheth ene ese tenmehn aarti neeehee 643 
MODEM sical Aannttain ah nn anon ance noun aan aun aeatan 645 
MUMCOPPIMN .estscceerk dea seer ieasteear sn teees etait nde oesadi anor danadin aitedee: 654 
MINER eoen Ave ad ett etd erie Bade dihaeie nat acGhaera dees 655 
MUM cles coe, Sozseesiek cack aes de caceviewd sacs vienna etna aedioesecaceardle nvthcbaodr ethan daeebeees 664 
MAU evccec tected secre cess athes de csevsbewdh cues stone keto edison oiuerdna test sch ohnbdhaeabcha chives 666 
MIOQO scsi gesestees thea che thsnre Guneceutioes setae avtems Gee arian uaseodsleainan ees 667 
MISALOMS eocns Beck A eeitacig meee avinand ead csdnadacinta badass 668 
MISCH ENS vee tek dctndhccathitniet es teananaddhndnddanaia dananwad 669 
MISTOMUS  iicccessenee acco etter abies d eaied denice Meaienhuivamiedendeteee eae 670 
P(A 0 Peer reenter EE rere rgerecrrret Prreercrerrrree rer rt rer eer rerrerer retest eer rerrrrntre rer eerrre reer rire 671 
MOK INE ss2eiccees. Be edeness gS craze beadhec essa vtecedecaghte dd raiestgaste iste sataneseer ee eddeci hoses 672 
XMOAMAD sss seh eid dik Minn dinaubamnnamanuaedudieaiaeanent: 672 
KOM Siac cd fsvetscastena sedheasdtsadsscdazaa cats tages ina attain ust ae dation Hua nadia ae 676 
XPIMLOP PIN ss si soasceseeseSeazeede ct snzest dhezecuceaecautzsadsaduacugedecuzsabisdniatgesegidersdh shteaeatdgeriaeena 677 
XIDIFO Pisa dseseteseaedetesdiyceuevdescducessinthieaeyddgedsceisiutsaeineitavenseuiiateis hesedviasl aattntiaucaneies 677 
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gethostid(2), gethostname(2), getpagesize(2), getpid(2), getuid(2), idle(2), iop1(2), profil(2), recv(2), 
sigvec(2), undocumented(2), vhangup(2), vm86(2), acosh(3), getdiren-tries(3), ctrlaltde1(8), dmesg(8), 
fdformat(8), fdisk(8), fsck.minix(8), ipcrm(8), ipcs(8), sync(8), sd(4), clear(1), clock(8), domainname(1), 
mkfs.minix(8), mkswap(8), passwd(1), rdev(8), reset(1), setfdprm(8), setserial(8), shutdown(8), kbdrate(8), 
update state(8), chkdupexe(1), cytune(8) copyright 1992, 1993, 1994, 1995 Rickard E. Faith 
(faith@cs.unc.edu). 


unlink(2), remove 


), 
), 


getdents(2), 11seek(2), readdir(2), syslog(2), console.4 copyright 1994, 1995 Andries Brouwer (aeb@cwi.n1). 


mount(2) copyright 1993 Rickard E. Faith (faithecs.unc.edu), copyright 1994 Andries E. Brouwer 
(aeb@cwi.n1). 


adjtimex(2), bdflush(2), ipc(2), modify 1dt(2), obsolete(2), socketcall(2), unimplemented(2) copyright © 1995 
M ichael Chastain (mec@she11.portal.com). 


accept(2), getpeername(2), listen(2), 1seek(2), getpriority(2), getsockname(2), getsockopt(2), ioct1(2), 
killpg(2), mmap(2), readlink(2), send(2), setpgid(2), setregid(2), setreuid(2), shut-down(2), sigblock(2), 
sigpause(2), socket(2), socketpair(2), statfs(2),truncate(2), alloca(3), fclose(3), ferror(3), fflush(3), 
fread(3), fseek(3), getpass(3), mailaddr(7), popen(3), printf(3), scant(3), setbuf(3), stdarg(3), stdio(3), 
banner(6), cal(1), co1(1), colcrt(1), colrm(1), column(1), fstab(5), getoptprog(1), logger(1), 1ook(1), 1pc(8), 
1pd(8), 1pq(1), 1pr(1), 1prm(1), 1ptest(1), mesg(1), mount(8), pac(8), ping(8), syslog.cont(5), sysloga(8), 
tsort(8), vipw(1), write(1), vi(1), rev(1), bitt(1), tset(1), w(1), aliases(5), ftp(1), ftpd(8), ineta(8), 
newaliases(1), rcp(1), resolver(5), rexecd(8), rlogin(1), routed(8), rpc.rusersd(8), rpc.rwalld(8), rsh(1), 
rshd(8), rup(1), rusers(1), rwal1(1), rwho(1), rwhod(8), sendmail(8), sliplogin(8), talk(1), talka(8), telnet(1), 
telnetd(8), tftp(1), tftpd(8), timed(8), timedc(8), traceroute(8) copyright © 1980, 1983, 1985, 1989, 1990, 
1991, 1992 T he Regents of the U niversity of California. All rights reserved. 


getitimer(2) copyright 1993 by Darren Senn (sinster@scintilla.santa-clara.ca.us). 
modules(2), ksyms(1), insmod(1), 1smod(1), rmmoa(1) copyright © 1994, 1995 Bjorn Ekwall (bjorn@biox.se). 


msgct1(2), msgget(2), msgop(2), semct1(2), semget(2), semop(2), ftok(3), ipc(5) copyright 1993 Giorgio Ciucci 
(giorgio@crcc. it). 
( 


setgid(2), setuid(2), realpath(3) copyright © 1994, GraeneW. Wilford. 
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shmct1(2), shmget(2), shmop(2) copyright © 1993 Luigi P. Bai (1pb@softint.com) July 28, 1993. 
sigaction(2), signal(2), sigsetops(3) copyright © 1994 M ike Battersby (mike@starbug.apana.org.au). 


stat(2) copyright © 1992 Drew Eckhardt (drewecs.colorado.edu), M arch 28, 1992. Parts copyright © 1995 
Nicolai Langfeldt (jan1eifi.uio.no), January 1, 1995. 


sysinfo(2), adjustclock(9), ctrl-alt-de1(9), filesystems(9), file table(9), file table init(9), get empty 
filp(9), grow files(9), in group p(9), insert file free(9), kernel mktime(9), proc sel(9), put file last(9), 
remove file free(9) copyright © 1993 by Dan M iner (dminer@nyx.cs.du.edu). 


wait(2), wait4(2), confstr(3), ctermid(3), fnmatch(3), fpathcont(3), getcwd(3), getopt(3), gets(3), isalpha(3), 
malloc(3), signal(7), sleep(3), sutfixes(7), sysconf(3), system(3), hier(7), assert(3), glob(3), killpg(3), 
locale(7), localeconv(3), puts(3), raise(3), readv(3), setlocale(3) copyright © 1993 by Thomas K oenig 
(ig25@rz.uni-karlsruhe.de). 


abort(3), abs(3), acos(3),asin(3), asinh(3),atan(3), atan2(3), atann(3), atexit(3), atof(3), atoi(3), ato1(3), 
pemp(3), bcopy(3), bstring(3), byteorder(3), bzero(3), ceil(3), closedir(3), confstr(3), copysign(3), cos(3), 
cosh(3), ctime(3), difftime(3), div(3), drand4a(3), drem(3), ecvt(3), ert(3), exec(3), exit(3), exp(3), fabs(3), 
ffs(3), fgetgrent(3), fgetpwent(3), fmod(3), fopen(3), frexp(3), gevt(3), getenv(3), getgrent(3), getgrnam(3), 
gethostbyname(3), getm-ntent(3), getnetent(3), getprotoent(3), getpw(3), getpwent(3), getpwnam(3), 
getservent(3), getusershel1(3), hypot(3), index(3), inet(3), infnan(3), initgroups(3), isint(3), j0(3), 1abs(3), 
ldexp(3), 1div(3), 1gamma(3), mblen(3), mostowcs(3), motowc(3), memccpy(3), mem-chr(3), memcmp(3), memcpy(3), 
memfrob(3), memmem(3), memmove(3), memset(3), mkstemp(3), Mktemp(3), modf(3), on exit(3), opendir(3), 


( 
psignal(3), putenv(3), putpwent(3), qsort(3), rand(3), random(3), readdir(3), resolver(3), rewinddir(3), rint(3), 
( 


scandir(3), seekdir(3), setenv(3), siginterrupt(3), sin(3), sinh(3), sqrt(3), stremp(3), strcat(3), strchr(3), 
stremp(3), strcol1(3), strcepy(3), strdup(3), strerror(3), strfry(3), strftime(3), string(3), strien(3), strp- 
break(3), strptime(3), strsep(3), strsignal(3), strspn(3), strstr(3), strtod(3), strtok(3), str-to1(3), 
strtoul(3), strxfrm(3), swab(3), tan(3), tanh(3), telldir(3), tempnam(3), tmpfile(3), tmpnam(3), toupper(3), 
tzset(3), usleep(3), westombs(3), wetomb(3) copyright 1993 D avid M etcalfe (david@prism.demon.co.uk). 


add timer(9), console ioct1(4), ttyname(3), ves(4) copyright © 1995 Jim Van Zandt (jrvavanzandt.mv.com). 


catgets(3), catopen(3), hostid(1) copyright 1993 M itchum D Souza (m.dsouza@mrc -applied- 
psychology .cambridge.ac.uk), 


fa(4) copyright © 1993 M ichael H aardt (michael@cantor.informatik.rwth-aachen.de) and 1994, 1995 Alain 
Knaff (Alain. Knaff@imag.fr). 


getutent(3) copyright 1995 M ark D. Roth (roth@uiuc. edu). 

hsearch(3) copyright 1993 Ulrich D reoper (drepper@karlsruhe.gmd.de). 

iso88591(7), proc(5), sed(1) copyright 1993[nd]1995 D aniel Quinlan (quinlan@yggdrasil.com). 
st(4) copyright 1995 Robert K. Nichols (Robert .K.Nichols@att.com). 

agetty(8) copyright © by W.Z. Venema (wietse@wzv.win.tue.n1), Peter O rbaek (poe@daimi.aau.dk). 
cfdisk(8) copyright 1994 Kevin E. Martin (martin@cs.unc. edu). 

chfn(1), chsh.1 Copyright © 1994 by Salvatore V alente (svalente@athena.mit. edu). 

crond(8), crontab(1) copyright 1994 M atthew Dillon (dillon@apollo.west.oic.com). 


kil1(1) copyright 1994 Salvatore V alente (svalente@mit.edu), copyright 1992 Rickard E. Faith 
(faith@cs.unc.edu). 


klogd(8), sysklogd(8) copyright 1994 Greg W ettstein, Enjellic Systems D evelopment. 
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setterm(1) copyright 1990 Gordon Irlam (gordoni@cs.ua.oz.au). Copyright 1992 Rickard E. Faith 
(faith@cs.unc.edu). 


tunelp(8), ps(1), psupdate(8) copyright © 1992 Michael K. Johnson (johnsonm@nigel.vnet.net). 
xineta(1) copyright © 1992 by Panagiotis T sirigotis. 

bash(1) copyright 1995 Chet Ramey (chet@ins.cwru.edu). 

adduser(8) copyright 1995 by T ed H ajek, 1994 by lan M urdock. 

e2fsck(8) copyright 1993, 1994 by TheodoreTs’o. 

free(1), tload(1) copyright © 1993 M att Welsh (mdwe@sunsite.unc.edu). 

top(1) copyright 1992 Robert J. Nation. 

vmstat(8) copyright © 1994 H enry W are (a1172@yfn.ysu. edu). 


bdftopet(1x), beforelight(1x), bitmap(1x), editres(1x), fsinfo(1x), flsfonts(1x),fstobdt(1x), iceauth(1x), 
imake(1x), Lbxproxy(1x), Indir(1Xx), makedepend(1x), makestrs(1x), mkdirhier(1X), mkfontdir(1x), oclock(1x), 
resize(1x), sessreg(1x), showrgb(1Xx), smproxy(1x), startx(1x), x11perf(1Xx), x11perfcomp(1x), xauth(1x), 
xclipboard(1x), xclock(1x), xcmsdb(1x), xcon-sole(1x), xcutse1(1x), xdm(1x), xdpyinfo(1x), xf8éconfig(1x), 
xfd(1x), x¢s(1x), xhost(1x), xinit(1x), xkil1(1Xx), xlogo(1x), xlsatoms(1x), xlsclients(1x), x1sfonts(1x), 
xmag(1x), xmkmf(1X), xmodmap(1Xx), xon(1x), xprop(1x), xrdb(1x), xrefresh(1x), xset(1Xx), xsetroot(1x), xsm(1x), 
xsmclient(1Xx), xstdcmap(1x), xterm(1x), xwa(1Xx), xwininfo(1x), xwud(1x) copyright © 1993, 1994 X Consor- 
tium. 


portmap(8) copyright © 1987 Sun M icrosystems, copyright © 1990, 1991 T he Regents of the University of 
California. 


rpegen.new(1) copyright © 1988, 1990 Sun M icrosystems, Inc. 
rstart(1x), rstarta(1x) copyright © 1993 Quarterdeck O ffice Systems. 
showmount(8) copyright 1993 Rick Sladkey (jrs@world.std.com). 


twm(1x) copyright © 1993, 1994 X Consortium. Portions copyright 1988 Evans & Sutherland C omputer 
Corporation. Portions copyright 1989 H ewlett-Packard Company. 


xieperf.1x copyright 1993, 1994 by AGE Logic, Inc. 


M any thanks to all these contributors for providing excellent-quality man pages and also to the Free Software 
Foundation for providing the rest. 
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Introduction 


This section introduces and describes user commands. 


AUTHORS 


Look at the header of the manual page for the author(s) and copyright conditions. N ote that these can be different from page 


to page. 


addftinfo 


addftinfo— Add information to trot font files for use with grotf 


SYNOPSIS 


addftinfo [ -paramvalue... ] res unitwidth font 


DESCRIPTION 


addftinfo reads atroff font file and adds some additional font-metric information that is used by the groff system. The font 
file with the information added is written on the standard output. The information added is guessed using some parametric 
information about the font and assumptions about the traditional trot names for characters. The main information added 
is the heights and depths of characters. Theres and unitwidth arguments should be the sameas the corresponding param- 
eters in the esc file; font isthename of thefile describing the font; if font ends with I, the font will be assumed to be italic. 


OPTIONS 





Each of the f options changes one of the parameters that is used to derive the heights and depths. Like the existing quantities 
in the font file, each value is in inches/res for a font whose point size is unitwidth. param must be one of the following: 


x-height 
fig-heigh 
asc-heigh 


body -height 


cap-heigh 
comma -dep 
desc -dept 
body -dept 


h 





n 


h 


The height of lowercase letters without ascenders such as x 
The height of figures (digits) 

Theheight of characters with ascenders, such as b, d, or | 
The height of characters such as parentheses 

Theheight of uppercase letters such as A 

The depth of acomma 

The depth of characters with descenders, such asp, q, or y 
The depth of characters such as parentheses 


addftinfo makes no attempt to use the specified parameters to guess the unspecified parameters. If a parameter is not 
specified, the default will be used. The defaults are chosen to have the reasonable values for a Times font. 


SEE ALSO 


font(5) groff_font(5), groft(1), groff_char(7) 


afmtodit 


Groff Verson 1.09, 6 August 1992 


afmtodit —C reate font files for use with groff -Tps 


SYNOPSIS 


afmtodit [ -ns ][-ddesc file ][-eenc_ file ][-in ][-an ] afm file map_file font 


afmtodit > | 
DESCRIPTION 


afmtodit creates a font file for use with grotf and grops. afmtodit is written in Pel; you must have Perl version 3 installed in 
order to run afmtodit. afm_file isthe AFM (Adobe Font M etric) file for the font. map_file isa file that says which groff 
character names map onto each PostScript character name this file should contain a sequence of lines of the form: 


ps_char groff_char 


where ps_char isthe PostScript name of the character and groff_char isthe groff name of the character (as used in the groff 
font file) The same ps_char can occur multiple times in thefile each groff_char must occur, at most, once. font is the groff 
name of the font. If a PostScript character is in the encoding to be used for the font but is not mentioned in map_file, then 
afmtodit will put it in the grotf font file as an unnamed character, which can be accessed by the \n escape sequence in troff. 
The groff_font file will be output to a file called font. 


If thereis a downloadable font file for the font, it may be listed in the file /usr/1ib/groff/font/devps /download; See grops(1). 
If the -i option is used, afmtodit will automatically generate an italic correction, a left italic correction, and a subscript 


correction for each character (the significance of these parameters is explained in groff_font(5)); these parameters may be 
specified for individual characters by adding to the atm_file lines of the form: 
italicCorrectionps charn 


leftItalicCorrectionps charn 
subscriptCorrectionps charn 


where ps_char isthe PostScript name of the character, and n isthe desired value of the corresponding parameter in thou- 
sandths of an em. These parameters are normally needed only for italic (or oblique) fonts. 





OPTIONS 

-n Don’t output a ligatures command for this font. Use this with constant-width fonts. 

-s The font is special. T he effect of this option is to add the special command to the font file. 

-ddesc_file The device description file iSdesc_ file rather than the default pesc. 

-eenc_file The PostScript font should be reencoded to use the encoding described in enc_file. The format of 
enc_file iSdescribed in grops(1). 

-an Usen asthe dant parameter in the font file; this is used by grott in the positioning of accents. By 
default, afmtodit uses the negative of the ItalicAngle specified in theaf m file; with true italic 
fonts, it is sometimes desirable to use a slant that is less than this. If you find that characters from 


an italic font have accents placed too far to the right over them, then use the -a option to give the 
font a smaller slant. 


-in Generate an italic correction for each character so that the character’s width plus the character's 
italic correction is equal to n thousandths of an em plus the amount by which the right edge of the 
character’s bounding is to the right of the character's origin. If this would result in a negative italic 
correction, use a zero italic correction instead. 


Also generate a subscript correction equal to the product of the tangent of the slant of the font and 
four-fifths of the x-height of the font. I f this would result in a subscript correction greater than the 
italic correction, use a subscript correction equal to the italic correction instead. 

Also generate a left italic correction for each character equal to n thousandths of an em plus the 
amount by which the left edge of the character's bounding box is to the left of the character's 
origin. The left italic correction may be negative. 

This option is normally needed only with italic (or oblique) fonts. T he font files distributed with 
groff were created using an option of -ise for italic fonts. 





FILES 
/usr/lib/groff/font/devps/DESC D evice description file 
/usr/lib/groff/font/devps/F Font description file for font F 


/usr/lib/groff/font/devps/download List of downloadable fonts 
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/usr/lib/groff/font/devps/text.enc Encoding used for text fonts 
/usr/1ib/groff/font/devps/generate/textmap Standard mapping 
SEE ALSO 


groff(1), grops(1), groff_font(5), peri(1) 
Groff Verson 1.09, 14 February 1994 


ansi2knr 

ansi2knr— Convert ANSI C to Kernighan & RitchieC 
SYNOPSIS 

ansi2knr input_file output_file 
DESCRIPTION 


If No out put_file iS supplied, output goes to stdout. There are no error messages. 


ansi2knr recognizes functions by seeing anonkeyword identifier at the left margin, followed by a left parenthesis, with aright 
parenthesis as the last character on the line It will recognize a multiline header if the last character on each line but the last is 
a left parenthesis or comma. T hese algorithms ignore whitespace and comments, except that the function name must be the 
first thing on theline 





The following constructs will confuse it: 


m Any other construct that starts at the left margin and follows the above syntax (such as a macro or function call) 
m Macros that tinker with the syntax of the function header 


31 D eeamber 1990 


anytopnm 
anytopnm— Attempt to convert an unknown type of image file to a portable anymap 


SYNOPSIS 


anytopnm file 


DESCRIPTION 


anytopnm uses the file program, possibly augmented by the magic numbers file included with pampvus, to try to figure out 
what type of image file it is. If that fails (very few image formats have magic numbers), looks at the filevame extension. If 
that fails, punt. 


The type of the output file depends on the input file 
SEE ALSO 


pnmfile(1), pnm(5), file(1) 


BUGS 


It's a script. Scripts are not portable to non-UN IX environments. 


AUTHOR 
Copyright © 1991 by J ef Poskanzer 
27 July 1990 


= Ie 


appres 


appres— List x application resource database 


SYNOPSIS 


appres [[class [instance]] [-1] [toolkitoptions] 


DESCRIPTION 


The appres program prints the resources seen by an application (or subhierarchy of an application) with the specified class 
and instance names. It can be used to determine which resources a particular program will load. For example, 


% appres XTerm 
will list the resources that any xterm program will load. If no application class is specified, the class -appResTest- is used. 


To match a particular instancename, specify an instance name explicitly after the classname, or use the normal xt toolkit 
option. For example 


% appres XTerm myxterm 
or 


% appres XTerm -name myxterm 


To list resources that match a subhierarchy of an application, specify hierarchical class and instance names. The number of 
class and instance components must be equal, and theinstance name should not be specified with a toolkit option. For 
example, 


% appres Xman.TopLevelShell.Form xman.topBox. form 


will list the resources of widgets of xman topBox hierarchy. To list just the resources matching a specific level in the hierarchy, 
use the -1 option. For example, 


% appres XTerm.VT100 xterm.vt100 -1 
will list the resources matching the xterm vt10e widget. 


SEE ALSO 
X(1), xrdb(1), listres(1) 


AUTHOR 
Jim Fulton (MIT X Consortium) 
X Version 11 Release 6 


ar 


ar— Create, modify, and extract from archives 


SYNOPSIS 


ar [ - ] dmpqrtx[abcilosuvV] [ membername ] archive files ... 


DESCRIPTION 


TheGNU ar program creates, modifies, and extracts from archives. An archiveisa single file holding a collection of othe 
files in a structure that makes it possible to retrieve the original individual files (called members of the archive). 


The original files contents, mode (permissions), timestamp, owner, and group are preserved in thearchive, and may be 
reconstituted on extraction. 
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GNU ar can maintain archives whose menbers have names of any length; however, depending on how ar is configured on 
your systen, a limit on member-name length may be imposed (for compatibility with archive formats maintained with other 
tools). If it exists, the limit is often 15 characters (typical of formats related to a.out) or 16 characters (typical of formats 
related to coff). 


ar is considered a binary utility because archives of this sort are most often used as libraries holding commonly needed 
subroutines. 


ar will create an index to the symbols defined in rdocatable object modules in the archive when you specify the modifier s. 
Once created, this index is updated in the archive whenever ar makes a change to its contents (save for the q update 
operation). An archive with such an index speeds up linking to the library, and allows routines in the library to call each 
other without regard to thar placement in the archive. 

You May use nm -s Of nm —print-armap to list this index table. If an archive lacks the table, another form of ar called ranlib 
can be used to add just the table. 

ar insists on at least two arguments to execute: one keyletter specifying the operation (optionally accompanied by other 
keyletters specifying modifiers ), and the archive name to act on. 


M ost operations can also accept further files arguments, specifying particular files to operate on. 


OPTIONS 


GNU ar allows you to mix the operation code p and modifier flags mod in any order, within the first command-line 
argument. 


If you wish, you may begin the first command-line argument with a dash. 
The p keyletter specifies what operation to execute it may be any of the following, but you must specify only one of them: 
d D elete modules from the archive. Specify the names of modules to be ddeted as files ; the archive is 
untouched if you specify no files to delete. 
If you specify the v modifier, ar will list each module asit is ddeted. 
m Use this operation to move members in an archive 


The ordering of members in an archive can make a differencein how programs are linked using the 
library if a symbol is defined in more than one membe. 


If no modifiers are used with m, any members you namein the files arguments are moved to the end of 
the archive, you can use the a, b, or i modifiers to move them to a specified place instead. 


p Print the specified members of the archive to the standard output file. If the v modifier is specified, 
show the menbername before copying its contents to standard output. 


If you specify no files, all the files in the archive are printed. 
q Quick append; add files to the end of archive without checking for replacenent. 


The modifiers a, b, and i do not affect this operation; new menbers are always placed at the end of the 
archive. 


The modifier v makes ar list each file as it is appended. 
Since the point of this operation is speed, the archive’s symbol table index is not updated, even if it 
already existed; you can use ar s OF ranlib explicitly to update the symbol table index. 

r Insert files into archive (with reolacenent). T his operation differs from q in that any previously existing 
membe’s are deleted if their names match those being added. 
If one of the files named in files doesn’t exist, ar displays an error message and leaves undisturbed any 
existing members of the archive matching that name 
By default, new members are added at the end of the file, but you may use one of the modifiers a, b, or 
ito request placenent relative to some existing menber. 
The modifier v used with this operation elicits aline of output for each file inserted, along with one of 
the letters a or r to indicate whether the file was appended (no old member deleted) or replaced. 





‘ 


t Display a table listing the contents of archive or those of the files listed in files that are present in the 
archive. Normally, only the menbernameis shown; if you also want to see the modes (permissions), 
timestamp, owner, group, and size, you can request that by also specifying thev modifier. 

If you do not specify any files, all files in the archive are listed. 

If thereis more than one file with the same name (say, fie) in an archive (Say, b.a), ar t b.a fie will 
list only the first instance to see them all, you must ask for a complete listing— in our example, ar t 
b.a. 

x Extract members (named files) from the archive. You can use the v modifier with this operation to 
request that ar list each name as it extracts it. 

If you do not specify any files, all files in the archive are extracted. 


A number of modifiers (moa) may immediately follow the p keyletter, to specify variations on an operation's behavior, as 
follows: 


a Add new files after an existing member of the archive. If you use the modifier a, the name of an 
existing archive member must be present as the manbername argument, before the archive specifica- 
tion. 

b Add new files before an existing member of the archive If you use the modifier b, the name of an 


existing archive member must be present as the menbername argument, before the archive specifica 
tion (same as i). 


c Create the archive The specified archive is always created if it didn’t exist when you request an update. 
But a warning isissued unless you specify in advance that you expect to create it by using this modifier. 
i Insert new files before an existing member of the archive If you use the modifier i, thename of an 


existing archive member must be present as the manbername argument, before the archive specifica- 
tion. (same as b). 


1 This modifier is accepted but not used. 

0 Preserve the original dates of members when extracting them. If you do not specify this modifier, files 
extracted from thearchive will be stamped with the time of extraction. 

s W rite an object-file index into the archive or update an existing one, even if no other change is made 


to the archive. You may use this modifier flag ather with any operation, or alone Running ar s onan 
archive is equivalent to running ranlib on it. 

u Normally, ar r... insertsall files listed into the archive If you would like to insert only those of the 
files you list that are newer than existing members of the same names, use this modifier. Theu modifier 
is allowed only for the operation r (replace). In particular, the combination qu is not allowed, since 
checking the timestamps would lose any speed advantage from the operation q. 


v This modifier requests the verbose version of an operation. M any operations display additional 
information, such as filevames processed, when the modifier v is appended. 
Vv This modifier shows the version number of ar. 
SEE ALSO 
binutils entry in info; TheGNU Binary Utilities, Roland H. Pesch (October 1991); nm(1), aniib(1) 
COPYING 


Copyright © 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy 
and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting 
derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus Support, 5 N ovenber 1991 
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arch 


arch— Print architecture 


SYNOPSIS 


arch 


DESCRIPTION 


arch displays machine architecture type. 


SEE ALSO 


uname(1), uname(2) 


D edbian GNU/Linux, 15 January 1994 


GNU as 


GNU as—Theportable GN U assembler 
SYNOPSIS 


as [ -a ; -al | -as ][-D ][-f ][-I path ][-K ][-L ][-o objfile ][-R J[-v ][-w ][--\\\ 
files ...] 

i960-only options: 

[ -ACA! -ACA A | -ACB ! -ACC! -AKA! -AKB | -AKC! -AMC][-b ][-no-relax ] 


m680x0-only options: 
[ -1 1[-mc68000! -mc68010! -mc68e20] 


DESCRIPTION 


GNU as isreally a family of assemblers. If you use (or have used) the GNU assembler on one architecture, you should find a 
fairly similar environment when you use it on another architecture. Each version has much in common with the others, 
including object file formats, most assembler directives (often called pseudo-ops) and assembler syntax. 


For information on the syntax and pseudo-ops used by GNU as, seeas entry in info (or the manual Usngas TheGNU 
Assembler). 


as is primarily intended to assemble the output of the GNU C compiler gcc for use by the linker 1a. N everthdess, we've tried 
to make as assemble correctly everything that the native assembler would. T his doesn’t mean as always uses the same syntax 
as another assembler for the same architecture; for example, we know of several incompatible versions of 680x0 assembly 
language syntax. 


Each time you run as, it assembles exactly one source program. T he source program is made up of one or more files. (The 
standard input is also a file.) 


If as is given no filenames, it attempts to read oneinput file from theas standard input, which is normally your terminal. 
You may haveto type Ctrl-D to tell as thereisno more program to assemble. U se -- if you need to explicitly name the 
standard input file in your command line. 


as may write warnings and error messages to the standard error file (usually your terminal). T his should not happen when as 
isrun automatically by a compiler. Warnings report an assumption made so that as could keep assembling a flawed program; 
errors report a grave problem that stops the assembly. 


GNU as > | 


OPTIONS 

-al-al|-as Turn on assanbly listings; -a1, listing only, -as, symbols only, -a, everything. 

-D This option is accepted only for script compatibility with calls to other assemblers, it 
has no effect on as. 

-f “Fast”-skip preorocessing (assume source is compiler output). 

-I\path Add path to the search list for .include directives. 

-K Issue warnings when difference tables altered for long displacenents. 

-L K eep (in symbol table) local symbols, starting with L. 

-o\objfile N ame the object-file output from as. 

-R Fold data section into text section. 

-v Announcéas version. 

-W Suppress warning messages. 

--\'\files... Source files to assemble, or standard input (--). 

-Avar (W hen configured for Intel 960.) Specify which variant of the 960 architecture isthe 
target. 

-b (W hen configured for Intel 960.) Add code to collect statistics about branches taken. 

-no-relax (W hen configured for Intel 960.) D o not alter compare-and-branch instructions for 
long displacements; error if necessary. 

-1 (W hen configured for M otorola 68000.) Shorten references to undefined symbols to 
one word instead of two. 

-mc68000 | -mc68010!-mc68020 (W hen configured for M otorola 68000.) Specify which processor in the 68000 





family is the target (default 68020). 
O ptions may bein any order, and may be before, after, or between filenames. T he order of filenames is significant. 
Thedouble hyphens command (—) by itself names the standard input file explicitly, as one of the files for as to assemble 


Except for --, any command line argument that begins with a hyphen (-) isan option. Each option changes the behavior of 
as. No option changes the way another option works. An option is a hyphen followed by one or more letters; the case of the 
letter isimportant. All options are optional. 


The -o option expects exactly one filename to follow. T he filename may either immediately follow the option’s letter 
(compatible with older assemblers) or it may be the next command argument (GN U standard). 


T hese two command lines are equivalent: 


as -o0 my-object-file.o mumble.s 


as -omy-object-file.o mumble.s 


SEE ALSO 


as entry in info; Usingas: TheGNU Assemble; gec(1), 14(1). 


COPYING 


Copyright © 1991, 1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of 
this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to 
copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire 
resulting derived work is distributed under the terms of a permission notice identical to this one 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus Support, 21 January 1992 
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asc1iitopgm 
asciitopgm— Convert ASCII graphics into a portable graymap 


SYNOPSIS 


asciitopgm [-d divisor] height width [asciifile] 


DESCRIPTION 


Reads ASCII data as input. Produces a portable graymap with pixel values that are an approximation of the brightness of the 
ASCII characters, assuming black-on-white printing. In other words, a capital M is very dark, a period is very light, and a 
space is white. Input lines that are fewer than wi dt h characters are automatically padded with spaces. 


The divisor argument is a floating-point number by which the output pixds are divided; the default value is1.0. This can be 
used to adjust the brightness of the graymap; for example, if the imageis too dim, reduce the divisor. 


In keeping with (I believe) FORTRAN line-printer conventions, input lines beginning with a+ (plus) character are assumed 
to overstrike the previous line, allowing a larger range of gray values. 


This tool contradicts the message in the pbmtoascii Manual: “N ote that there is no asciitopbm tool— this transformation is 
one-way.” 


BUGS 
The table of ASCII-to-gray values is subject to interpretation, and, of course, depends on the typeface intended for the input. 


SEE ALSO 


pbmtoascii(1), pgm(5) 


AUTHOR 


Wilson H. Bent, Jr. (whb@usc.edu) 
26 D ecanber 1994 


atktopbm 


atktopbm— C onvert Andrew T oolkit raster object to portable bitmap 


SYNOPSIS 


atktopbm [atkfile] 


DESCRIPTION 


atktopbm reads an Andrew T oolkit raster object as input and produces a portable bitmap as output. 


SEE ALSO 


pbmtoatk(1), pbm(5) 
AUTHOR 
Copyright © 1991 by Bill Janssen 
26 Septenber 1991 


~ 


bash 


bash— GNU Bourne-again shal 
SYNOPSIS 


bash [options] [file] 


DESCRIPTION 


bash isan sh-compatible command language interpreter that executes commands read from the standard input or from afile 
bash also incorporates useful features from the Korn and C shells (ksh and csh). 


bash is ultimately intended to be a conformant implenentation of the IEEE PO SIX Shell and T ools specification (IEEE 
Working Group 10032). 


OPTIONS 


In addition to the single character shal options documented in the description of the set built-in command, bash interprets 
the following flags when it isinvoked: 


-c string If the -c flag is present, then commands are read from st ring. If there are arguments after the 
string, they are assigned to the postiona parametes, starting with so. 

-i If the -i flag is present, the shal isinteractive 

-s If the -s flag is present, or if no arguments remain after option processing, ther commands are 


read from the standard input. This option allows the positional parameters to be sat when 
invoking an interactive shell. 

- A single - signals the end of options and disables further option processing. Any arguments after 
the - are treated as filenames and arguments. An argument of — is equivalent to an argument 
of -. 


bash also interprets a number of multicharacter options. T o be recognized, these options must appear on the command line 
before the single- character options. 


-nore Do not read and execute the personal initialization file ~/.bashre if the shell is interactive. This 
option is on by default if the shell isinvoked as sh. 
-noprofile Do not read either the system-wide startup file /etc/profile or any of the personal initializa- 


tion files ~/.bash_profile, ~/.bash_login, Or ~/.profile. By default, bash normally reads these 
files when it isinvoked as alogin shdl. (See the “Invocation” section, later in this manual page.) 


-rcfile file Execute commands from file instead of the standard personal initialization file ~/.bashrc, if the 
shell is interactive. (See “Invocation.”) 

-version Show the version number of this instance of bash when starting. 

-quiet Do not be verbose when starting up (do not show the shell version or any other information). 
This is the default. 

-login M ake bash act asif it had been invoked asalogin shel. 

-nobraceexpansion Do not perform curly brace expansion. (See “Brace Expansion,” later in this manual page.) 

-nolineediting DonotusetheGNU readline library to read command lines if interactive 

-posix Change the behavior of bash where the default operation differs from the PO SIX 1003.2 


standard to match the standard. 


ARGUMENTS 


If arguments remain after option processing, and neither the -c nor the -s option has been supplied, thefirst argument is 
assumed to be the name of a file containing shal commands. If bash is invoked in this fashion, is set to the name of the file, 
and the positional parameters are set to the remaining arguments. bash reads and executes commands from this file, then 
exits. bash’s exit status is the exit status of the last command executed in the script. 


re | Part |: User Commands 


DEFINITIONS 
blank A space or tab. 
word A sequence of characters considered as a single unit by the shal. Also known as a token. 
name A word consisting only of alphanumeric characters and underscores and beginning with an 
alphabetic character or an underscore. Also referred to as an identifier. 
meta character A character that, when unquoted, separates words. O ne of the following: 
|, & 3, (,), < >, space, tab 
control operator A token that performs a control function. It is one of the following symbols: 
I], &, & & 5,33, (0), |, ewline> 
RESERVED WORDS 


Reserved words are words that have a special meaning to the shell. The following words are recognized as reserved when 
unquoted and either the first word of asimple command (see “Shell Grammar,” next) or the third word of a case or for 
command: 


! case do done elif else esac fi for function if in select then until while { } 


SHELL GRAMMAR 


SIMPLE COMMANDS 


A sample command is a sequence of optional variable assignments followed by words and redirections separated by blank and 
terminated by acontrol operator. The first word specifies the command to be executed. The remaining words are passed as 
arguments to the invoked command. 


The return value of a simple command isits exit status, or 128+n if the command is terminated by signal n. 


PIPELINES 
A pipdineis a sequence of one or more commands separated by the character |. The format for a pipeline is 
[!]command [ | command2 ... ] 


The standard output of command is connected to the standard input of command2. This connection is performed before any 
redirections specified by the command. (See the “Redirection” section, later in this manual page.) 


If the reserved word ! precedes a pipeline, the exit status of that pipeline is the logical not of the exit status of the last 
command. O therwise, the status of the pipdine is the exit status of the last command. The shell waits for all commands in 
the pipeline to taminate before returning a value 


Each command in a pipeline is executed as a separate process (that is, in a subshell). 


LISTS 


A lis isa sequence of one or more pipelines separated by one of these operators: ;, & &&, or |!, and terminated by one of 
these: ;, & OF <newline>. 


Of these list operators, && and |! have equal precedence, followed by ; and a, which have equal precedence. 


If acommand isterminated by the control operator a, the shell executes the command in the background in a subshell. The 
shell does not wait for the command to finish, and the return status is 2. Commands separated by a; are executed sequen- 
tially; the shell waits for each command to terminate in turn. The return status is the exit status of the last command 
executed. 

The control operators 3a and |! denote ano lists and or lists, respectively. An ano list has the form: 


command && command2 


command2 is executed if, and only if, command returns an exit status of Zero. 


- 


command2 is executed if, and only if, command returns a non-zero exit status. The return status of anp and or lists is the exit 
status of the last command executed in thelist. 


COMPOUND COMMANDS 
A compound command is one of the following: 
list) 


An or list has the form 


command command2 


ist is executed in asubshal. Variable assignments and built-in commands that affect the shell’s environment do not renain 
in effect after the command completes. The return status is the exit status of list. 

list; } 

list issimply executed in the current shell environment. This is known asa group command. The return status is the exit 
status of |i st. 

or name [ in word;] do list ; done 





Thelist of words following in is expanded, generating alist of items. T he variable nameis set to each element of this list in 
turn, and |ist isexecuted each time. If the in word is omitted, the for command executes! i st once for each positional 
parameter that is set. (See “Parameters,” later in this manual page ) 

select name [ in word;] dolist ; done 


The list of words following in is expanded, generating alist of items. T he set of expanded wordsis printed on the standard 
error, each preceded by anumbe. If the in word is omitted, the positional parameters are printed. (See “Parameters.”) The 
PS3 prompt is then displayed and alineread from the standard input. If the line consists of the number corresponding to 
one of the displayed words, then the value of name is set to that word. If the lineis empty, the words and prompt are 
displayed again. If or is read, the command completes. Any other value read causes name to be set to null. Theline read is 
saved in the variable RepLy. The list is executed after each selection until a break Or return command is executed. The exit 
status of select is the exit status of the last command executed in list, or zero if no commands were executed. 

case word in [ pattern [ | pattern ] 


A case command first expands word, and tries to match it against each pattern in turn, using the same matching rules as for 
pathname expansion. (See “PathnameE xpansion,” later in this manual page.) W hen a match is found, the corresponding list 
is executed. After the first match, no subsequent matches are attempted. T he exit status is zero if no patterns are matches. 

O therwise, it is the exit status of the last command executed in| ist. 

if list then list [ elif list then list ] ... [ else list ] fi 


The if list is executed. If its exit status is zero, the then list is executed. O therwise, each elif list is executed in turn, and if its 
exit status is zero, the corresponding then list is executed and the command completes. O therwise, the else list is executed, if 
present. T he exit status is the exit status of the last command executed, or zero if no condition tested True. 

while list do list done 


until list do list done 


The while command continuously executes the do list aslong as the last command in! ist returns an exit status of zero. The 
until command isidentical to the while command, except that the test is negated; the ao list is executed as long as the last 
command in!ist returnsanon-zero exit status. The exit status of the while and until commands isthe exit status of the last 
do list command executed, or zero if none was executed. 


[ function ] name () { list; } 
This defines a function named name. T he body of the function is the list of commands between {and }. This list is executed 


whenever nameis specified as the name of a simple command. The exit status of a function is the exit status of the last 
command executed in the body. (See “Functions,” later in this manual page) 
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COMMENTS 


In anoninteractive shell, or an interactive shal in which the -o interactive-comments option to the set builtin is enabled, a 
word beginning with # causes that word and all remaining characters on that line to be ignored. An interactive shal without 
the -o interactive-comments option enabled doesnot allow comments. 


QUOTING 


Quoting isused to remove the special meaning of certain characters or words to the shell. Quoting can be used to disable 
special treatment for special characters, to prevent reserved words from being recognized as such, and to prevent parameter 
expansion. 


Each of the meta characters listed earlier under “D efinitions” has special meaning to the shell and must be quoted if it is to 
represent itself. T here are three quoting mechanisms: the escape character, single quotes, and double quotes. 


A nonquoted backslash (\) is the escape character. It preserves the literal value of the next character that follows, with the 
exception of <newline>.If a \<newline> pair appears, and the backslash is not quoted, the \<newline> is treated asaline 
continuation; that is, it is effectively ignored. 


Enclosing characters in single quotes preserves the literal value of each character within the quotes. A single quote may not 
occur between single quotes, even when preceded by a backslash. 


Enclosing characters in double quotes preserves the literal value of all characters within the quotes, with the exception of, ', 
and \. The characters $ and ' retain their special meaning within double quotes. T he backslash retains its special meaning 
only when followed by one of the following characters: $, ', ", \, Or <newline>. A double quote may be quoted within double 
quotes by preceding it with a backslash. 


The special parameters * and e have special meaning when in double quotes. (See “Parameters,” next.) 


PARAMETERS 


A parame’ is an entity that stores values, somewhat like a variablein a conventional programming language. It can bea 
name, anumber, or one of the special characters listed under “Special Parameters,” following. For the shell’s purposes, a 
variable is a parameter denoted by aname 


A parameter is set if it has been assigned a value. The null string is a valid value O nce a variable is set, it may be unset only 
by using the unset built-in command. (See “Shell Built-in Commands,” later in this manual page.) 


A variable may be assigned to by a statement of the form: 


name=[val ue] 


If value iSnot given, the variable is assigned the null string. All values undergo tilde expansion, parameter and variable 
expansion, command substitution, arithmetic expansion, and quote removal. If the variable has its -i attribute set (see 
declare in “Shell Built-in Commands”) then val ue issubject to arithmetic expansion even if the $[...] syntax does not 
appear. W ord splitting isnot performed, with the exception of "sa", as explained under “Special Parameters.” Pathname 
expansion is not performed. 


POSITIONAL PARAMETERS 


A positional parameter is a parameter denoted by one or more digits, other than the single digit 0. Positional parameters are 
assigned from the shell’s arguments when it is invoked, and may be reassigned using theset built-in command. Positional 
parameters may not be assigned to with assignment statements. The positional parameters are temporarily replaced when a 
shell function is executed. (See “Functions,” later in this manual page.) 





When a positional parameter consisting of more than a single digit is expanded, it must be enclosed in braces. (See 
“Expansion,” later in this manual page.) 


SPECIAL PARAMETERS 
The shal treats several parameters specially. T hese parameters may only be referenced; assignment to then is not allowed. 


“oF 


* Expands to the positional parameters, starting from one. When the expansion occurs within double 
quotes, it expands to a single word with the value of each parameter separated by the first character 
of the rrs special variable T hat is, "s*" is equivalent to "$ic$2c...", where c is thefirst character of 
the value of the rrs variable If 1Fs isnull or unset, the parameters are separated by spaces. 

@ Expands to the positional parameters, starting from one. When the expansion occurs within double 
quotes, each parameter expands as a separate word. T hat is, "$e" is equivalent to "$i""$2" .... 

W hen there are no positional parameters, "se" and $e expand to nothing (in other words, they are 


removed). 
# Expands to the number of positional parameters in decimal. 
2 Expands to the status of the most recently executed foreground pipeline. 


- Expands to the current option flags as specified upon invocation, by the set built-in command, or 
those set by the shell itself (such as the -; flag). 

$ Expands to the process 1D of theshdl.In a () subshdl, it expands to the process 1D of the current 
shell, not the subshdl. 

! Expands to the process |D of the most recently executed background (asynchronous) command. 

Q Expands to thename of the shdl or shell script. This is set at shell initialization. If bash is invoked 

with a file of commands, is set to thename of that file. If bash is started with the -c option, then is 

set to the first argument after the string to be executed, if oneis present. O therwise, it is set to the 

pathname used to invoke bash, as given by argument zero. 

Expands to the last argument to the previous command, after expansion. Also set to the full 

pathname of each command executed and placed in the environment exported to that command. 


SHELL VARIABLES 
The following variables are set by the shell: 
PPID Theprocess!ID of the shdl’s parent. 
PWD The current working directory as set by the cd command. 
OLDPWD The previous working directory as set by the cd command. 
REPLY Sé to the line of input read by the read built-in command when no arguments are 
supplied. 
UID Expands to the user ID of the current user, initialized at shdll startup. 
EUID Expands to the effective use ID of the current user, initialized at shal startup. 
BASH Expands to the full pathname used to invoke this instance of bash. 
BASH_VERSION Expands to the version number of this instance of bash. 
SHLVL Incremented by one each time an instance of bash is started. 
RANDOM Each time this parameter is referenced, a random integer is generated. T he sequence 


of random numbers may be initialized by assigning a value to RANDom. If RANDOM is 
unset, it loses its special properties, even if it is subsequently reset. 

SECONDS Each time this parameter is referenced, the number of seconds since shell invocation 
is returned. If a value is assigned to seconps, the value returned upon subsequent 
references is the number of seconds since the assignment plus the value assigned. If 
seEconps is unset, it loses its special properties, even if it is subsequently reset. 

LINENO Each time this parameter is referenced, the shell substitutes a decimal number 
representing the current sequential line number (starting with 1) within a script or 
function. When notin ascript or function, the value substituted is not guaranteed to 
be meaningful. When in a function, the value is not the number of the source line 
that the command appears on (that information has been lost by the time the 
function is executed), but is an approximation of thenumber of simple commands 
executed in the current function. If LTNENo is unset, it loses its special properties, even 
if it is subsequently reset. 
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HISTCMD The history number, or index in the history list, of the current command. If HI1sTcup 
is unset, it loses its special properties, even if it is subsequently reset. 

OPTARG The value of the last option argument processed by the getopts built-in command. 
(See “Shall Built-in Commands,” later in this manual page). 

OPTIND The index of the next argument to be processed by the getopts built-in command. 
(See “Shall Built-in C ommands.”) 

HOSTTYPE Automatically set to a string that uniquely describes the type of machine on which 
bash is executing. T he default is system-dependent. 

OSTYPE Automatically set to a string that describes the operating system on which bash is 


executing. T he default is system-dependent. 


The following variables are used by the shell. In some cases, bash assigns a default value to a variable; these cases are noted in 
the following list: 


IFS Theinternal field separator that is used for word splitting after expansion and to split 
lines into words with the read built-in command. T he default value is 
<space><tab><newline>. 

PATH Thesearch path for commands. It isa colon-separated list of directories in which the 
shell looks for commands. (See “Command Execution,” later in this manual page). 
The default path is system-dependent, and is set by the administrator who installs 
bash. A common value is /usr/gnu/bin: /usr/local/bin: /usr/ucb: /bin:/usr/bin:. 


HOME Thehome directory of the current user; the default argument for the ca built-in 
command. 
CDPATH Thesearch path for the cd command. T his is a colon-separated list of directories in 


which the shell looks for destination directories specified by the ca command. A 
sample value is .:~:/usr. 

ENV If this parameter is set when bash is executing a shell script, its value is interpreted as 
a filename containing commands to initializethe shal, asin .bashrc. T he value of 
ENV is subjected to parameter expansion, command substitution, and arithmetic 
expansion before being interpreted as a pathname. patH is not used to search for the 
resultant pathname. 


MAIL If this parameter is set to a filename and the maILpatH variable is not set, bash informs 
the user of the arrival of mail in the specified file. 
MAILCHECK Specifies how often (in seconds) bash checks for mail. The default is6a seconds. 


W hen it is time to check for mail, the shal does so before prompting. If this variable 
is unset, the shell disables mail checking. 

MAILPATH A colon-separated list of pathnames to be checked for mail. T he message to be 
printed may be specified by separating the pathname from the message with a 
question mark (2). $_ stands for the name of the current mailfile. 

Example: 


MAILPATH\ 
='/usr/spool/mail/bfox?"You have 
mail":”/shell-mail?"$_has mail!"' 


bash Supplies a default value for this variable but the location of the user mail files 
that it uses is system-dependent (for example, /usr/spool/mail/$USER). 


MAIL_WARNING If set, and a file that bash is checking for mail has been accessed since the last time it 
was checked, the message “T he mail in mail-file has been read” is printed. 

PS1 The value of this parameter is expanded (see “Prompting,” later in this manual page) 
and used as the primary prompt string. The default value is bash\s. 

PS2 The value of this parameter is expanded and used as the secondary prompt string. 


The default is >. 


PS3 


PS4 


HISTSIZE 


HISTFILE 


HISTFILESIZE 


OPTERR 


PROMPT_COMMAND 


IGNOREEOF 


TMOUT 


FCEDIT 
FIGNORE 


INPUTRC 


notify 


history_control HISTCONTROL 


command_oriented_history 


glob_dot_filenames 


allow-null_glob_expansion 


histchars 


bash 


The value of this parameter is used as the prompt for the select command. (See 
“Shell Grammar,” earlier in this manual page.) 

The value of this parameter is expanded and the value is printed before each 
command bash displays during an execution trace. T he first character of ps4 is 
replicated multiple times, as necessary, to indicate multiple leves of indirection. The 
default is+. 

Thenumber of commands to remember in the command history, (See “H istory,” 
later in this manual page.) T he default value is see. 

Thename of thefilein which command history is saved. (See “History.”) The 
default value is ~/.bash_history. If unset, the command history isnot saved when an 
interactive shell exits. 

Themaximum number of lines contained in the history file W hen this variable is 
assigned a value, the history file is truncated, if necessary, to contain no more than 
that number of lines. T he default value is 50. 

If set to the value 1, bash displays error messages generated by the getopts built-in 
command. (See “Shell Built-in Commands.”). opTerr isinitialized to 1 each timethe 
shell is invoked or ashal script is executed. 

If set, the value is executed as acommand prior to issuing each primary prompt. 
Controls the action of the shal on receipt of an cor character as the sole input. If set, 
the value is the number of consecutive Eor characters typed as the first characters on 
an input line before bash exits. If the variable exists but does not have a numeric 
value, or has no value, the default value is 10. If it does not exist, Eor signifies the end 
of input to theshdl. This is only in effect for interactive shdls. 

If set to a value greater than zero, the value isinterpreted as the number of seconds 
to wait for input after issuing the primary prompt. bash terminates after waiting for 
that number of secondsif input does not arrive. 

The default editor for the fc built-in command. 

A colon-separated list of suffixes to ignore when performing filename completion. 
(See “Readline,” later in this manual page.) A filename whose suffix matches one of 
the entries in Fianore is excluded from the list of matched filenames. A sample value 
IS.o:7. 

The filename for the readline startup file, overriding the default of ~/.inputrc. (See 
“Readline”) 

If set, bash reports terminated background jobsimmediately, rather than waiting 
until before printing the next primary prompt. (See also the -b option to the set 
built-in command.) 

If set to a value of ignorespace, lines that begin with a space character are not entered 
on the history list. If set to a value of ignoredups, lines matching the last history line 
are not entered. A value of ignoreboth combines the two options. If unset, or if set to 
any other value than the preceding, all lines read by the parser are saved on the 
history list. 

If set, bash attempts to save all lines of a multiple line command in the same history 
entry. T his allows easy reediting of multiline commands. 

If set, bash includes filenames beginning with a period (.) in the results of pathname 
expansion. 

If set, bash allows pathname patterns which match no files (see “Pathname 
Expansion”) to expand to anull string, rather than thensdves. 

The two or three characters that control history expansion and tokenization. (See 
“History Expansion,” later in this manual page) The first character is the history 
expansion character; that is, the character that signals the start of a history expansion, 
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nolinks 


hostname_completion_file HOSTFILE 
noclobber 


auto_resume 


no_exit_on_failed_exec 


cdable_vars 


EXPANSION 


normally !. The second character is the quick substitution character, which is used as 
shorthand for rerunning the previous command entered, substituting one string for 
another in the command. The default is ~. The optional third character is the 
character that signifies that the remainder of the line is a comment, when found as 
the first character of aword, normally #. The history comment character causes 
history substitution to be skipped for the remaining words on the line It does not 
necessarily cause the shal parser to treat the rest of the line as a comment. 

If set, the shall does not follow symbolic links when executing commands that 
change the current working directory. It uses the physical directory structure instead. 
By default, bash follows the logical chain of directories when performing commands 
that change the current directory, such as cd. See also the description of the -p 
option to the set builtin (“Shell Built-in Commands’). 

Contains the name of afilein the same format as /etc/hosts that should be read 
whe theshal needs to complete a hostname T hefile may be changed interactively; 
the next time hostname completion is attempted bash adds the contents of the new 
file to the already existing database. 

If set, bash does not overwrite an existing file with the>, >a, and <> redirection 
operators. T his variable may be overridden when creating output files by using the 
redirection operator >! instead of >. (See also the -c option to the set built-in 
command.) 

This variable controls how the shell interacts with the user and job control. If this 
variable is set, single word simple commands without redirections are treated as 
candidates for resumption of an existing stopped job. Thereis no ambiguity allowed; 
if there is more than one job beginning with the string typed, the job most recently 
accessed is sdected. The name of a stopped job, in this context, is the command line 
used to start it. If set to the value exact, the string supplied must match the name of 
a topped job exactly; if set to substring, the string supplied needs to match a 
substring of the name of a stopped job. The substring value provides functionality 
analogous to the»? job ID . (See “Job Control,” later in this manual page) If set to 
any other value, the supplied string must be a prefix of a stopped job’s name this 
provides functionality andogousto thes job id. 

If this variable exists, a noninteractive shal will not exit if it cannot execute the file 
specified in the exec built-in command. An interactive shal does not exit if exec 
fails. 

If thisis set, an argument to theca built-in command that is not a directory is 
assumed to be the name of a variable whose value is the directory to change to. 


Expansion is performed on the command line after it has been split into words. T here are seven kinds of expansion 
performed: brace expansion, tilde expansion, parameter and variable expansion, command substitution, arithmetic expan- 
sion, word splitting, and pathname expansion. 


The order of expansions is as follows: brace expansion, tilde expansion, parameter, variable, command, and arithmetic 
substitution (done in a left-to-right fashion), word splitting, and pathname expansion. 


On systems that can support it, there is an additional expansion available: process substitution. 


Only brace expansion, word splitting, and pathname expansion can change the number of words of the expansion; other 
expansions expand a single word to a single word. T he single exception to this is the expansion of "sa", as explained earlier. 


(See “Parameters.”) 


BRACE EXPANSION 


Brace expansion is a mechanism by which arbitrary strings may be generated. T his mechanism is similar to pathname 
expansion, but the filaaames generated need not exist. Patterns to be brace expanded take the form of an optional preamble, 
followed by a series of comma-separated strings between a pair of braces, followed by an optional postamble. T he preamble is 
prepended to each string contained within the braces, and the postamble is then appended to each resulting string, 
expanding left to right. 


Brace expansions may be nested. T he results of each expanded string are not sorted; left to right order is preserved. For 
example, a{d,c,b}e expands into ade ace abe. 


Brace expansion is performed before any other expansions, and any characters special to other expansions are preserved in the 
result. It is strictly textual. bash does not apply any syntactic interpretation to the context of the expansion or the text 
between the braces. 


A correctly formed brace expansion must contain unquoted opening and closing braces, and at least one unquoted comma. 
Any incorrectly formed brace expansion is left unchanged. 


This construct is typically used as shorthand when the common prefix of the strings to be generated is longer than in the 
preceding example, such as 


mkdir /usr/local/src/bash/{old,new, dist, bugs} 


or 


chown root /usr/{ucb/{ex, edit}, lib/{ex?.?*,how_ex}} 


Brace expansion introduces a slight incompatibility with traditional versions of sh, the Bourne shell. sh does not treat 
opening or closing braces specially when they appear as part of a word, and preserves them in the output. bash removes 
braces from words as a consequence of brace expansion. For example, aword entered to sh aS file{1,2} appears identically in 
the output. The same word is output as file1 file2 after expansion by bash. If strict compatibility with sh is desired, start 
bash with the -nobraceexpansion flag (see “O ptions,” earlier in this manual page) or disable brace expansion with the +o 
braceexpand option to the set command. (See “Shell Built-in Commands.”) 


TILDE EXPAN SION 


If a word begins with a tilde character (~), all of the characters preceding the first slash (or all characters, if there is no slash) 
are treated as a possible login name. If this login nameis the null string, the tildeis replaced with the value of the parameter 
Home. If Home is unset, the home directory of the user executing the shell is substituted instead. 


If a+ follows the tilde, the value of Pwo replaces the tilde and + If a- follows, the value of oLppwo is substituted. If the value 
following the tilde is a valid login name, thetilde and login name are replaced with the home directory associated with that 
name. If thenameis invalid, or the tilde expansion fails, the word is unchanged. 


Each variable assignment is checked for unquoted instances of tildes followinga : or =. In these cases, tilde substitution is 
also performed. Consequently, one may use pathnames with tildes in assignments to PATH, MAILPATH, and cppaTH, and the shell 
assigns the expanded value. 


PARAMETER EXPAN SION 


Thes character introduces parameter expansion, command substitution, or arithmetic expansion. T he parameter name or 
symbol to be expanded may be enclosed in braces, which are optional but serve to protect the variable to be expanded from 
characters immediately following it which could be interpreted as part of the name. 


${parameter } The value of parameter iS substituted. The braces are required when parameter iSa positional parameter 
with more than onedigit, or when parameter is followed by acharacter that is not to be interpreted as part 
of itsname 


In each of the following cases, word is subject to tilde expansion, parameter expansion, command substitution, and arithmetic 
expansion. bash tests for a parameter that is unset or null; omitting the colon results in atest only for a parameter that is 
unset. 
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${parameter :-word} Use default values. If parameter iS unset or null, the expansion of word is substituted. O thewise the 
value of parameter is Substituted. 

{parameter :=word} Assign default values. If parameter iS unset or null, the expansion of word is assigned to parameter. 
The value of parameter isthen substituted. Positional parameters and special parameters may not be 
assigned to in this way. 

{parameter :2word} Display Error if null or unset. If parameter iSnull or unset, the expansion of word (or a message to 
that effect if word isnot present) is written to the standard error and the shall, if itis not interactive, 
exits. O therwise, the value of parameter is Substituted. 














${parameter :+word } Use Alternate Value. If parameter iSnull or unset, nothing is substituted; otherwise, the expansion 
of word issubstituted. 
${#par ameter } The length in characters of the value of parameter iS Substituted. If parameter is* or a@, the length 
substituted is the length of « expanded within double quotes. 
{parameter #word} Theword is expanded to produce a pattern just asin pathname expansion. If the pattern matches 
{parameter ##word } the beginning of the value of par amet er , then the expansion is the value of parameter with the 
shortest matching pattern deleted (the # case) or the longest matching pattern deleted (the ## case). 
{parameter %word } Theword is expanded to produce a pattern just asin pathname expansion. If the pattern matches a 
${paramet er %%word} trailing portion of the value of par amet er, then the expansion is the value of parameter with the 
shortest matching pattern deleted (thes case) or the longest matching pattern deleted (the %% case). 
COMMAND SUBSTITUTION 


Command substitution allows the output of a command to replace the command name 
There are two forms: 

$(command ) 

or 


“command' 


performs the expansion by executing command and replacing the command substitution with the standard output of the 
command, with any trailing newlines deleted. 

W hen the old-style backquote form of substitution is used, backslash retains its literal meaning except when followed by $, ', 
or \. When using the $(command ) form, all characters between the parentheses make up the command; noneare treated 
specially. 

Command substitutions may be nested. To nest when using the old form, escape the inner backquotes with backslashes. 

If the substitution appears within double quotes, word splitting and pathname expansion are not performed on the results. 


ARITHMETIC EXPANSION 
Arithmetic expansion allows the evaluation of an arithmetic expression and the substitution of the result. T here are two 
formats for arithmetic expansion: 
$[expression] 
$( (expression) ) 
The expression is treated as if it were within double quotes, but a double quote inside the braces or parentheses is not treated 
specially. All tokensin the expression undergo parameter expansion, command substitution, and quote removal. Arithmetic 
substitutions may be nested. 
The evaluation is peformed according to the rules listed under “Arithmetic Evaluation,” later in thissection. If expression iS 
invalid, bash prints a message indicating failure and no substitution occurs. 


PROCESS SUBSTITUTION 


Process substitution is supported on systems that support named pipes (FIFOs) or the /dev/fa method of naming open files. 
It takesthe form of <(iist) or >(list ). The process list is run with its input or output connected to aFIFO or somefilein / 
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dev/fd. Thename of this file is passed as an argument to the current command asthe result of the expansion. If the >(I ist ) 
form is used, writing to the file will provide input for list. If the<iist ) form is used, the file passed as an argument should 
be read to obtain the output of list. 


On systems that support it, process substitution is paformed simultaneously with parameter and variable expansion, 
command substitution, and arithmetic expansion. 


WORD SPLITTING 


The shdl scans the results of parameter expansion, command substitution, and arithmetic expansion that did not occur 
within double quotes for word splitting. 


The shdl treats each character of 1Fs as a delimiter, and splits the results of the other expansionsinto words on these 
characters. If the value of 1Fs is exactly <space><tab><newline>, the default, then any sequence of 1Fs characters serves to 
ddimit words. If 1Fs has a value other than the default, then sequences of the whitespace characters space and tab are ignored 
at the beginning and end of the word, as long as the whitespace character is in the value of 1Fs (an 1Fs whitespace character). 
Any character in 1rs that is not 1rs whitespace, along with any adjacent rrs whitespace characters, delimits afidd. A 
sequence of Fs whitespace characters is also treated as a delimiter. If the value of 1Fs is null, no word splitting occurs. 1Fs 
cannot be unset. 


Explicit null arguments ("" or '') are retained. Implicit null arguments, resulting from the expansion of parameters that have 
no values, are removed. 


N ote that if no expansion occurs, no splitting is performed. 


PATHNAME EXPANSION 


After word splitting, unless the - option has been set, bash scans each word for the characters *, 2, and [. If one of these 
characters appears, then the word is regarded as a pattern and replaced with an alphabetically sorted list of pathnames 
matching the pattern. If no matching pathnames are found, and the shell variable allow_null_glob_expansion is unset, the 
word isleft unchanged. If the variable is set, and no matches are found, the word is removed. W hen a pattern is used for 
pathname generation, the character (.) at the start of aname or immediately following asiash must be matched explicitly, 
unless the shell variable glob_dot_filenames iS set. The slash character must always be matched explicitly. In other cases, the 
(.) character is not treated specially. 


The special pattern characters have the following meanings: 

* M atches any string, including the null string. 

2 M atches any single character. 

[.-.] M atches any one of the enclosed characters. A pair of characters separated by a minus sign denotes a range 
any character lexically between those two characters, inclusive, is matched. If the first character following 


the | isa! ora, then any character not enclosed is matched. A - or ] may be matched by including it as 
the first or last character in the set. 


QUOTE REMOVAL 
After the preceding expansions, all unquoted occurrences of the characters \, ', and " are removed. 


REDIRECTION 


Before a command is executed, its input and output may be redirected using a special notation interpreted by the shell. 
Redirection may also be used to open and close files for the current shell execution environment. T he following redirection 
operators may precede or appear anywhere within a simple command or may follow a command. Redirections are processed 
in the order they appear, from left to right. 


In the following descriptions, if the file descriptor number is omitted, and the first character of the redirection operator is<, 
the redirection refers to the standard input (file descriptor a). If the first character of the redirection operator is >, the 
redirection refers to the standard output (file descriptor 1). 
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Theword that follows the redirection operator in the following descriptions is subjected to brace expansion, tilde expansion, 
parameter expansion, command substitution, arithmetic expansion, quote renoval, and pathname expansion. If it expands to 
morethan oneword, bash reports an error. 


N ote that the order of redirections is significant. For example, the command: 

Is > dirlist 2>&1 

directs both standard output and standard error to thefiledir!ist, while the command 

1s 2>81 > dirlist 

directs only the standard output to file dir! ist, because the standard error was duplicated as standard output before the 
standard output was redirected to dirlist. 


REDIRECTING INPUT 


Redirection of input causes the file whose name results from the expansion of word to be opened for reading on file 
descriptor n, or the standard input (file descriptor 0) ifn isnot specified. 


The general format for redirecting input is 


[n ]<word 


REDIRECTING OUTPUT 


Redirection of output causes the file whose name results from the expansion of word to be opened for writing on file 
descriptor n, or the standard output (file descriptor 1) if n isnot specified. If the file does not exig, it is created; if it does 
exist it is truncated to zero size. 


The general format for redirecting output is 

[n ]>word 

If the redirection operator is >!, then the value of the -c option to the set built-in command is not tested, and file creation is 
attempted. (See also the description of noclobber under “Shell Variables,” earlier in this manual page) 


APPENDING REDIRECTED OUTPUT 


Redirection of output in this fashion causes the file whose name results from the expansion of word to be opened for 
appending on file descriptor n, or the standard output (file descriptor 1) ifn isnot specified. If the file does not exist, it is 
created. 


The general format for appending output is 


[n]>>word 


REDIRECTING STANDARD OUTPUT AND STANDARD ERROR 


bash allows both the standard output (file descriptor 1) and the standard error output (file descriptor 2) to be redirected to 
the file whose nameis the expansion of word with this construct. 


There are two formats for redirecting standard output and standard error: 
&>word 
and 


>aword 


Of the two forms, the first is preferred. T his is sanantically equivalent to 
>word 2>81 


HERE-DOCUMENTS 


This type of redirection instructs the shell to read input from the current source until a line containing only word (with no 
trailing blanks) is seen. All of the lines read up to that point are then used as the standard input for acommand. 


aaa 


No parameter expansion, command substitution, pathname expansion, or arithmetic expansion is peformed on word. If any 
characters in word are quoted, the deli miter istheresult of quote removal on word, and thelinesin the here- document arenot 
expanded. Otherwise, all lines of thehere- document are subjected to parameter expansion, command substitution, and 

arithmetic expansion. In the latter case, the pair \<newline> iSignored, and \ must be used to quote the characters \, $, and '. 


If the redirection operator is <<-, then all leading tab characters are stripped from input lines and the line containing 
ddimiter. This allows here-documents within shell scripts to be indented in anatural fashion. 
DUPLICATING FILE DESCRIPTORS 
The redirection operator: 
[n ]<&word 


The format of here documents is as follows: 


<<[-]word here-document delimiter 


is used to duplicate input file descriptors. If word expands to one or more digits, the file descriptor denoted by n ismade to be 
a copy of that file descriptor. If word evaluates to -, file descriptor n isclosed. If n isnot specified, the standard input (file 
descriptor o) is used. 
The operator: 
[n ]>&word 
is used similarly to duplicate output file descriptors. If n isnot specified, the standard output (file descriptor 1) isused. Asa 
special case, if n isomitted, and word does not expand to one or more digits, the standard output and standard error are 
redirected as described previously. 

OPENING FILE DESCRIPTORS FOR READING AND WRITING 
The redirection operator: 
[n ]<>word 


causes the file whose name is the expansion of word to be opened for both reading and writing on file descriptorn, or asthe 
standard input and standard output if n is not specified. If the file does not exist, it is created. 


FUNCTIONS 


A shell function, defined as described above under “Shell Grammar,” stores a series of commands for later execution. 
Functions are executed in the context of the current shell; no new process is created to interpret them (contrast this with the 
execution of a shell script). When a function is executed, the arguments to the function become the positional parameters 
during its execution. The special parameter # is updated to reflect the change Positional parameter a is unchanged. 


Variables local to the function may be declared with the 1oca1 built-in command. Ordinarily, variables and their values are 
shared between the function and its caller. 


If the built-in command return is executed in a function, the function completes and execution resumes with the next 
command after the function call. When a function completes, the values of the positional parameters and the special 
parameter # are restored to the values they had prior to function execution. 


Function names may be listed with the -f option to the declare or typeset built-in commands. Functions may be exported 
so that subshells automatically have them defined with the -f option to the export builtin. 


Functions may be recursive No limit isimposed on thenumber of recursive calls. 


ALIASES 


The shal maintains a list of aliases that may be set and unset with the alias and unalias built-in commands. (See “Shall 
Built-in Commands”). The first word of each command, if unquoted, is checked to see if it hasan alias. If so, that word is 
replaced by the text of the alias. The alias name and the reolacenent text may contain any valid shal input, including the 
meta characters listed above, with the exception that the alias name may not contain =. The first word of the replacenent text 
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is tested for aliases, but a word that is identical to an alias being expanded is not expanded a second time This means that 
one may alias 1s to 1s -F, for instance, and bash does not try to recursively expand the replacenent text. | f the last character 
of the alias value is a blank, then the next command word following the alias is also checked for alias expansion. 


Aliases are created and listed with the alias command, and removed with the unalias command. 


There isno mechanism for using arguments in the reolacanent text, as in csh. If arguments are needed, a shell function 
should be used. 


Aliases are not expanded when the shal is not interactive. 


Therules concerning the definition and use of aliases are somewhat confusing. bash always reads at least one complete line of 
input before executing any of the commands on that line Aliases are expanded when a command is read, not when it is 
executed. Therefore, an alias definition appearing on the same line as another command does not take effect until the next 
lineof input is read. T his means that the commands following the alias definition on that line are not affected by the new 
alias. This behavior is also an issue when functions are executed. Aliases are expanded when the function definition is read, 
not when the function is executed, because a function definition is itsdf a compound command. As a consequence, aliases 
defined in afunction are not available until after that function is executed. To be safe always put alias definitionson a 
separate line, and do not use alias in compound commands. 





N ote that for almost every purpose, aliases are superseded by shell functions. 


JOB CONTROL 


Job control refers to the ability to selectivey stop (suspend) the execution of processes and continue (resume) their execution 
at a later point. A user typically enploys this facility via an interactive interface supplied jointly by the systen’s terminal 
driver and bash. 


The shdl associates a job with each pipdine It keeps a table of currently executing jobs, which may be listed with the jobs 
command. W hen bash starts a job asynchronously (in the background), it prints a line that looks like this: 


[1] 25647 


indicating that this job is job number 1 and that the process ID of the last process in the pipeline associated with this job is 
25647. All of the processes in a single pipeline are members of the same job. bash uses the job abstraction as the basis for job 
control. 


To facilitate the implementation of the user interface to job control, the system maintains the notion of a current terminal 
process group ID. M anbers of this process group (processes whose process group ID is equal to the current terminal process 
group ID ) receive keyboard-generated signals such as saint. T hese processes are said to bein the foreground. Background 
processes are those whose process group ID differs from the terminal’s; such processes are immune to keyboard-generated 
signals. O nly foreground processes are allowed to read from or write to the terminal. Background processes that attempt to 
read from (write to) the terminal are sent a s1GTTIN (s1GTTOU) signal by the terminal driver, which, unless caught, suspends 
the process. 


If the operating system on which bash is running supports job control, bash allows you to use it. T yping the suspend 
character (typically *z, contro1-z) while a process is running causes that process to be stopped and returns you to bash. 
Typing the delayed suspend character (typically *y, control-y) causes the process to be stopped when it attempts to read 
input from the terminal, and control to be returned to bash. You may then manipulate the state of this job, using the bg 
command to continueit in the background, the tg command to continueit in the foreground, or the ki11 command to kill 
it. A Ctrl+Z takes effect immediately, and has the additional side effect of causing pending output and typeahead to be 
discarded. 


There areanumber of ways to refer to ajob in theshdl. T he character » introduces ajob name Job number n may be 
referred to as sn. A job may also be referred to using a prefix of the name used to start it, or using a substring that appears in 
its command line For example %ce refers to a stopped ce job. If a prefix matches more than one job, bash reports an error. 
Using %?ce, on the other hand, refers to any job containing the string ce in its command line If the substring matches more 
than one job, bash reports an error. The symbols %% and %+ refer to the shell’s notion of the current job, which isthe last job 
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stopped while it was in the foreground. T he previous job may be referenced using %-.In output pertaining to jobs (for 
example, the output of the jobs command), the current job is always flagged with a+, and the previous job with a-. 


Simply naming ajob can be used to bring it into the foreground: %1 isasynonym for fg %1, bringing job 1 from the 
background into the foreground. Similarly, 1 & resumes job 1 in the background, equivalent to bg %1. 


Theshdl learns immediately whenever ajob changes state N ormally, bash waits until it is about to print a prompt before 
reporting changes in ajob’s status so as to not interrupt any other output. If the -b option to the set built-in command is set, 
bash reports such changes immediately. (See also the description of the notify variablein “Shall Variables,” earlier in this 
manual page.) 


If you attempt to exit bash while jobs are stopped, the shell prints a message warning you. You may then use the jobs 
command to inspect their status. If you do this, or try to exit again immediatey, you are not warned again, and the stopped 
jobs are terminated. 


SIGNALS 


W hen bash is interactive it ignores staTerm (So that kill @ does not kill an interactive shell), and sta@int is caught and 
handled (so that the wait built-in is interruptible). In all cases, bash ignores staaurr. If job control isin effect, bash ignores 
SIGTTIN, SIGTTOU, and SIGTSTP. 


Synchronous jobs started by bash have signals set to the values inherited by the shell from its parent. When job control isnot 
in effect, background jobs (jobs started with &) ignore stamnt and stcaumT. Commands run as a result of command substitu- 
tion ignore the keyboard-generated job control signals s1cTTIN, stGTToU, and sIGTSTP. 


COMMAND EXECUTION 


After a command has been split into words, if it results in a simple command and an optional list of arguments, the 
following actions are taken. 


If the command name contains no slashes, the shell attempts to locate it. If there exists a shdl function by that name, that 
function is invoked as described earlier in “Functions.” If the name does not match a function, the shell searches for it in the 
list of shell builtins. If amatch is found, that builtin is invoked. 


If the name is nether a shal function nor a builtin, and contains no slashes, bash searches each element of the PATH for a 
directory containing an executable file by that name. If the search is unsuccessful, the shdl prints an error message and 
returns a nonzero exit status. 


If the search is successful, or if the command name contains one or more slashes, the shal executes the named program. 
Argument a is set to the name given, and the renaining arguments to the command are set to the arguments given, if any. 


If this execution fails because the file is not in executable format, and the file is not a directory, it isassumed to bea shal 
script, a file containing shell commands. A subshell is spawned to execute it. This subshal reinitializes itself, so that the effect 
is as if anew shel had been invoked to handle the script, with the exception that the locations of commands renenbered by 
the parent (see hash under “Shall Built-in Commands”) are retained by the child. 


If the program isa file beginning with #!:, the renainder of the first line specifies an interpreter for the program. T he shell 
executes the specified interpreter on operating systems that do not handle this executable format themselves. The arguments 
to the interpreter consist of a single optional argument following the interpreter name on the first line of the program, 
followed by the name of the program, followed by the command arguments, if any. 


ENVIRONMENT 


When a program is invoked, it is given an array of strings called the environment. Thisisa list of name/value pairs, of the 
form name=value. 


The shal allows you to manipulate the environment in several ways. On invocation, the shal scansits own environment and 
creates a parameter for each name found, automatically marking it for export to child processes. Executed commands inherit 
the environment. T he export and declare -x commands allow parameters and functions to be added to and ddeted from the 
environment. If the value of a parameter in the environment is modified, the new value becomes part of the environment, 
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replacing the old. The environment inherited by any executed command consists of the shell’s initial environment, whose 
values may be modified in the shell, less any pairs removed by the unset command, plus any additions via the export and 
declare -x commands. 

The environment for any smple command or function may be augmented temporarily by prefixing it with parameter 
assignments, as described earlier in “Parameters.” T hese assignment statements affect only the environment seen by that 
command. 


If the -k flag is set (see the set built-in command), then all parameter assignments are placed in the environment for a 
command, not just those that precede the command name. 


W hen bash invokes an external command, the variable is set to the full path name of the command and passed to that 
command in its environment. 


EXIT STATUS 


For the purposes of the shell, acommand which exits with a zero exit status has succeeded. An exit status of zero indicates 
success. A non-zero exit status indicates failure. When a command terminates on a fatal signal, bash uses the value of 
128+signal as the exit status. 


If acommand is not found, the child process created to execute it returns a status of 127. If acommand is found but is not 
executable, the return status is 126. 


bash itself returns the exit status of the last command executed, unless a syntax error occurs, in which caseit exits with anon- 
zero value. (See also the exit built-in command.) 
PRO MPTING 


W hen executing interactively, bash displays the primary prompt ps1 when it is ready to read acommand, and the secondary 
prompt ps2 when it needs more input to complete a command. bash allows these prompt strings to be customized by 
inserting a number of backslash-escaped special characters that are decoded as follows: 


\t Thecurrent timein HH: uM: $s format 

\d The date in “W eekday M onth Date” format (for example, “Tue M ay 26”) 

\n Newline 

\s Thename of the shdl, the basename of so (the portion following the final slash) 

\w The current working directory 

\w The basename of the current working directory 

\u The username of the current user 

\h The hostname 

\# Thecommand number of this command 

\! The history number of this command 

\ If the effective UID iso, a#, otherwiseas 

\nnn The character corresponding to the octal number nnn 

\\ A backslash 

\ Begin a sequence of nonprinting characters, which could be used to embed a terminal control sequence 
into the prompt 

\ End a sequence of nonprinting characters 

The command number and the history number are usually different: the history number of acommand isits position in the 

history list, which may include commands restored from the history file (see “History,” later in this manual page), while the 





command number is the position in the sequence of commands executed during the current shell session. After the string is 
decoded, it is expanded via parameter expansion, command substitution, arithmetic expansion, and word splitting. 


cas 
READLINE 


Thisis the library that handles reading input when using an interactive shell, unless the -nolineediting option is given. By 
default, the line editing commands are similar to those of emacs. A vi-style line editing interface is also available 


In this section, the emacs-style notation is used to denote keystrokes. C ontrol keys are denoted by c-key; for example, c-n 
means Ctrl-N . Similarly, meta keys are denoted by m-key, SO m-x Means Meta-x. (On keyboards without a meta key, m-x 
means Esc-X; that is, press the Escape key, then the X key. This makes ESC the meta prefix. The combination m-c-x means 
Esc-Control-x, or press the Escape key then hold the C ontrol key while pressing the X key.) 


T he default key-bindings may be changed with a /.inputre file T he value of the shal variable 1nputac, if set, is used instead 
of “/.inputrc. O ther programs that use this library may add thar own commands and bindings. 


For example, placing 


M-Control-u: universal -argument 


or 


C-Meta-u: universal-argument 


into the /.inputre would makem-c-u execute the readline command universal- argument.T he following symbolic character 
names are recognized: RUBOUT, DEL, ESC, LFD, NEWLINE, RET, RETURN, SPC, SPACE, and TAB. In addition to command names, 
readline allows keysto be bound to a string that is inserted when the key is pressed (a macro). 


Readline is customized by putting commands in an initialization file The name of this file is taken from the value of the 
rnpuTRC variable. If that variable is unset, the default is ~/.inputrc. When a program that uses the readline library starts up, 
the init file is read, and the Key bindings and variables are set. T here are only afew basic constructs allowed in the readline 
init file Blank lines are ignored. Lines beginning with a# are comments. Lines beginning with a¢ indicate conditional 
constructs. O ther lines denote key bindings and variable settings. 


T he syntax for controlling key bindingsin the ~/.inputre file is simple. All that is required is the name of the command or 
the text of amacro and a key sequence to which it should be bound. The name may be specified in oneof two ways: asa 
symbolic key name, possibly with M eta- or Control- prefixes, or asa key sequence When using theform keyname: function- 
name Of macro, keyname isthe name of a key spelled out in English. For example 

Control-u: universal -argument 


Meta-Rubout: backward-kill-word 
Control-o: ">&output" 


In the preceding example, c-u is bound to the function universal-argument, M-DEL is bound to the function backward-kill- 
word,and ¢-o isbound to run the macro expressed on the righthand side (that is, to insert the text >aoutput into the line). 


In thesecond form, ‘keyseq":function-name OF macro, keyseq differs from keyname in that strings denoting an entire key 
sequence may be specified by placing the sequence within double quotes. Some GN U emacs-style key escapes can be used, as 
in the following example: 

"\C-u": universal-argument 

"\C-x\C-r": re-read-init-file 

"\e[11°": "Function Key 1" 


In this example, c-u isagain bound to the function universal-argument. C-x ¢-r iS bound to the function re-read-init-file, 
and Esc[11” isbound to insert the text Function Key 1.7 he full set of escape sequences is 


\C- Control prefix 

\M- M eta prefix 

\e An escape character 
\\ Backslash 

\" Literal “ 


\' Literal ‘ 


Part |: User Commands 


When entering the text of a macro, single or double quotes should be used to indicate a macro definition. Unquoted text is 
assumed to be a function name. Backslash will quote any character in the macro text, including " and'. 


bash allowsthe current readline key bindings to be displayed or modified with the bind built-in command. T he editing 
mode may be switched during interactive use by using the -o option to the set built-in command. (See “Shel Built-in 


Commands.”) 


Readline has variables that can be used to further customizeits behavior. A variable may be set in the inputrc file with a 


statement of the form: 


set variable-name value 





Except where noted, readline variables can take the values on or off. The variables and their default values are as follows: 


horizontal-scroll-mode (Off) 


editing-mode (emacs) 
mark-modified-lines (off) 
bell-style (audible) 
comment-begin ("#") 
meta-flag (Off) 


convert-meta (On) 


output-meta (Off) 


completion-query-items (100) 


keymap (emacs) 


show-all-if-ambiguous (Off) 


expand-tilde (off) 


W hen set to on, makes readline use a Single line for display, scrolling the input 
horizontally on a single screen line when it becomes longer than the screen width 
rather than wrapping to a new line 

Controls whether readline begins with a set of key bindings similar to emacs or vi. 
editing-mode can be set to either emacs Or vi. 

If set to on, history lines that have been modified are displayed with a preceding 
asterisk (*). 

Controls what happens when readline wants to ring the terminal bell. If set to none, 
readline never rings the bell. If set to visible, readline uses a visible bal if oneis 
available. If set to audible, readline attempts to ring the taminal’s bal. 

The string that is inserted in vi mode when the vi-comment command is executed. 

If set to On, readline will enable aght-bit input (that is, it will not strip the high bit 
from the characters it reads), regardless of what the terminal claims it can support. 
If set to On, readline will convert characters with the eighth bit set to an ASCII key 
sequence by stripping the aghth bit and prepending an escape character (in effect, 
using escape as the meta prefix). 

If set to On, readline will display characters with the eighth bit set directly rather 
than as a meta-prefixed escape sequence. 

This determines when the user is queried about viewing the number of possible 
completions generated by the possible-completions command. It may be set to any 
integer value greater than or equal to zero. If the number of possible completions is 
greater than or equal to the value of this variable, the user is asked whether or not he 
wishes to view them; otherwise they are smply listed on theterminal. 

Se the current readline keymap. The set of legal keymap names is emacs, emacs- 
standard, emacs-meta, emacs-ct1x, vi, vi-move, vi-command, and vi-insert. vi iS 
equivalent to vi-command; emacs is equivalent to emacs-standard. The default value is 
emacs; the value of editing-mode also affects the default keymap. 

This alters the default behavior of the completion functions. If set to on, words 
which have more than one possible completion cause the matches to be listed 
immediately instead of ringing the bell. 

If set to on, tilde expansion is performed when readline attempts word completion. 








Readline implenents a facility similar in spirit to the conditional compilation features of the C preprocessor that allows key 
bindings and variable settings to be performed asthe result of tests. T here are three parser directives used. 


$if 


The sit construct allows bindings to be made based on the editing mode, the 
terminal being used, or the application using readline. The text of the test extends 
to the end of the line no characters are required to isolate it. 


bash 


mode The mode= form of the sit directive is used to test whether 
readline iSiN emacs or vi mode This may be used in conjunction 
with the set keymap command, for instance, to set bindingsin the 
emacs-standard and emacs-ctlx keymaps only if readline is starting 
out in emacs mode 


term The term= form may be used to include taminal-specific key 
bindings, perhaps to bind the key sequences output by the 
terminal's function keys. The word on the right side of the = is 
tested against the full name of the terminal and the portion of the 
terminal name before the first -. This allows sun to match both 
sun and sun-cmd, for instance. 


application Th@application construct is used to include application-specific 
settings. Each program using the readline library sets the 
application name, and an initialization file can test for a particular 
value. This could be used to bind key sequences to functions 
useful for a specific program. For instance, the following 
command adds a key sequence that quotes the current or previous 
word in bash: 


$if Bash 
# Quote the current or previous word 
"\O-xg": "\eb\"\ef\"" 


$endif 
$endif This command, as shown in the preceding example, terminates an sit command. 
$else Commands in this branch of the sit directive are executed if the test fails. 


readline Commands may be given numeric arguments, which normally act as a repeat count. Sometimes, however, it is the 
sign of the argument that is significant. Passing anegative argument to a command that actsin the forward direction (such as 
kill-line) causes that command to act in a backward direction. Commands whose behavior with arguments deviates from 
this are noted. 


W hen acommand is described as killing text, the text deleted is saved for possible future retrieval (yanking). The killed text 
is saved in a kill-ring. C onsecutive kills cause the text to be accumulated into oneunit, which can be yanked all at once 
Commands that do not kill text separate the chunks of text on the kill-ring. 


The following isa list of the names of the commands and the default key sequences to which they are bound. 


Commandsfor M oving 





beginning-of-1ine (C-a) M oveto thestart of the current line. 

end-of-line (C-e) M ove to the end of the line 

forward-char (C-f) M ove forward a character. 

backward-char (C-b) M ove back a character. 

forward-word (M-f) M ove forward to the end of the next word. W ords are composed of alphanu- 
meric characters (letters and digits). 

backward-word (M-b) M ove back to the start of this, or the previous, word. W ords are composed of 
alphanumeric characters (letters and digits). 

clear-screen (C-1) Clear the screen leaving the current line at the top of the screen. With an 


argument, refresh the current line without clearing the screen. 
redraw-current-line Refresh the current line. By default, this is unbound. 
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Commandsfor M anipulating the H istory 





accept-line (Newline, Return) 


previous-history (C-p) 
next-history (C-n) 
beginning-of-history (M-<) 
end-of-history (M->) 
reverse-search-history (c-r) 


forward-search-history (C-s) 
non-incremental-reverse- 


search-history (M-p) 


non-incremental-forward- 
search-history (M-n) 


history-search-forward 


history-search-backward 


yank-n th-arg (M-C-y) 


yank-last-arg (M-., M-_) 


shell-expand-line (M-C-e) 


history-expand-line (M-") 
insert-last-argument (M-., M-_) 
operate-and-get-next (C-o) 


Commandsfor Changing T ext 


Accept the line regardless of where the cursor is. If this line is non-empty, add it 
to the history list according to the state of the H1sT-conTroL variable. If the lineis 
a modified history line, then restore the history line to its original state 

Fetch the previous command from the history list, moving back in the list. 
Fetch the next command from the history list, moving forward in the list. 

M oveto the first line in the history. 

M oveto the end of the input history, that is, the line currently bang entered. 
Search backward starting at the current line and moving “up” through the 
history as necessary. Thisisan incremental search. 

Search forward starting at the current line and moving “down” through the 
history as necessary. Thisisan incremental search. 

Search backward through the history, starting at the current line using a non- 
incremental search for a string supplied by the user. 

Search forward through the history using a nonincremental search for a string 
supplied by the user. 

Search forward through the history for the string of characters between the start 
of the current line and the current point. This is a nonincremental search. By 
default, this command is unbound. 

Search backward through the history for the string of characters betwem the start 
of the current line and the current point. This is anonincremental search. By 
default, this command is unbound. 

Insert the first argument to the previous command (usually the second word on 
the previous line) at point (the current cursor position). With an argument n, 
insert thenth word from the previous command (the words in the previous 
command begin with word @). A negative argument inserts the nth word from 
the end of the previous command. 

Insert the last argument to the previous command (the last word on the previous 
line). With an argument, behave exactly like @codefyank-nth-argg. 

Expand the line the way the shell does when it reads it. This performs alias and 
history expansion as well as all of the shel word expansions. See “History 
Expansion,” later in this manual page, for a description of history expansion. 
Perform history expansion on the current line See “H istory Expansion.” 

A synonym for yank-last-arg. 

Accept the current line for execution and fetch the next linerdative to the 
current line from the history for editing. Any argument is ignored. 





delete-char (C-d) 


backward-delete-char (Rubout) 
quoted-insert (C-q, C-v) 


tab-insert (C-v Tab) 
self-insert (a, b, A, 1, !, ...) 


D elete the character under the cursor. If point is at the beginning of the line, 
there are no characters in the line, and the last character typed was not c-a, then 
return EOF. 


D elete the character behind the cursor. W hen given anumevic argument, save 
the ddeted text on the kill-ring. 


Add the next character that you type to the line verbatim. T his is how to insert 
characters like c-q, for example. 


Insert a tab character. 
Insert the character typed. 


transpose-chars (C-t) 


transpose-words (M-t) 
upcase-word (M-u) 
downcase-word (M-1) 


capitalize-word (M-c) 


Killing and Yanking 


- 


D rag the character before point forward over the character at point. Point moves 
forward as well. If point is at the end of theline then transpose the two 
characters before point. N egative arguments don’t work. 

D rag the word behind the cursor past the word in front of the cursor, moving 
the cursor over that word as wal. 

U ppercase the current (or following) word. W ith a negative argument, do the 
previous word, but do not move point. 

Lowercase the current (or following) word. W ith a negative argument, do the 
previous word, but do not move point. 

Capitalize the current (or following) word. W ith a negative argument, do the 
previous word, but do not move point. 





kill-line (C-k) 
backward-kill-line (C-x C-Rubout) 
UNIX-line-discard (C-u) 
kill-whole-line 


kill-word (M -d) 


backward-kill-word (M-Rubout) 
UNIX-word-rubout (C-w) 


delete-horizontal-space 
yank (C-y) 
yank-pop (M-y) 


Numeric Arguments 


Kill the text from the current cursor position to the end of the line. 

Kill backward to the beginning of the line 

Kill backward from point to the beginning of theline. 

Kill all characters on the current line, no matter where the cursor is. By default, 
thisis unbound. 

K 

en 


ill from the cursor to the end of the current word, or if between words, to the 
d of the next word. W ord boundaries are the same as those used by forward- 
word. 


Kill the word behind the cursor. W ord boundaries are the same as those used by 
backward-word. 


Kill the word behind the cursor, using whitespace as a word boundary. The word 
boundaries are different from backward-kill-word. 


D elete all spaces and tabs around point. By default, thisis unbound. 

Yank the top of the kill ring into the buffer at the cursor. 

Rotate the kill-ring, and yank the new top. Only works following yank or yank- 
pop. 














digit-argument (M-0, M-1, ...,M—) 


universal-argument 


Completing 


Add this digit to the argument already accumulating, or start a new argument. 
m— starts a negative argument. 

Each time thisis executed, the argument count is multiplied by four. T he 
argument count is initially one so executing this function the first time makes 
the argument count four. By default, this isnot bound to a key. 





complete (TAB) 


possible-completions (M-?) 


insert-completions 


complete-filename (M-/) 


Attempt to perform completion on the text before point. Bash attempts 
completion treating the text as a variable (if the text begins with $), username (if 
the text begins with ~), hostname (if the text begins with e), or command 
(including aliases and functions) in turn. If none of these produces a match, 
filename completion is attempted. 

List the possible completions of the text before point. 

Insert all completions of the text before point that would have been generated by 
possible-completions. By default, thisisnot bound to a key. 

Attempt filename completion on the text before point. 


continues 
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Completing 





ist the possible completions of the text before point, treating it as a filename. 
ttenpt completion on the text before point, treating it as a username 


possible-filename-completions (C-x /) I 
A 
possible-username-completions (C-x °) List the possible completions of the text before point, treating it asa username. 
A 
i 
Vv 


complete-username (M-~) 
ttenpt completion on the text before point, treating it as a shell variable 
ist the possible completions of the text before point, treating it as a shell 


complete-variable (M-$) 
possible-variable-completions (C-x $) 















































ariable. 
complete-hostname (M-@) Attempt completion on the text before point, treating it as a hostname 
possible-hostname-completions (C-x @) List the possible completions of the text before point, treating it as a hostname. 
complete-command (M-!) Attempt completion on the text before point, treating it as acommand name. 





Command completion attempts to match the text against aliases, reserved words, 
shell functions, builtins, and finally executable filenames, in that order. 


possible-command-completions (C-x !) List the possible completions of the text before point, treating it as a command 
name 

dynamic-complete-history (M-TAB) Attenpt completion on the text before point, comparing the text against lines 
from the history list for possible completion matches. 

complete-into-braces (M-{) Perform filename completion and return the list of possible completions enclosed 


within braces so the list is available to the shall. (See “Brace Expansion,” earlier in 
this manual page.) 


Keyboard M acros 





start-kbd-macro (C-x () Begin saving the characters typed into the current keyboard macro. 

end-kbd-macro (C-x )) Stop saving the characters typed into the current keyboard macro and save the 
definition. 

call-last-kbd-macro (C-x e) Re-execute the last keyboard macro defined, by making the characters in the 


macro appear asif typed at the keyboard. 





M iscdlaneous 

re-read-init-file (C-x C-r) Read in the contents of your init file and incorporate any bindings or variable 
assignments found there. 

abort (C-g) Abort the current editing command and ring the terminal’s bell (subject to the 
setting of bell-style). 

do-uppercase-version (M-a, M-b, ...) Run the command that is bound to the corresponding uppercase character. 

prefix-meta (ESC) M etafy the next character typed. ESC -f is equivalent to M eta-f. 

undo (C-_, C-x C-u) Incremental undo, separately remembered for each line. 

revert-line (M-r) Undo all changes made to thisline This islike typing the undo command 
enough times to return theline to its initial state. 

tilde-expand (M-") Perform tilde expansion on the current word. 

dump-functions Print all of the functions and their key bindings to the readline output stream. If 
a numeric argument is supplied, the output is formatted in such a way that it can 
be made part of an inputrc file. 

display-shell-version (C-x C-v) Display version information about the current instance of bash. 

emacs-editing-mode (C-e) W hen in vi editing mode, this causes a switch to emacs editing mode. 

HISTORY 


W hen interactive, the shal provides access to the command history, thelist of commands previously typed. T he text of the 
last HISTSIZE Commands (default 500) is saved in a history list. The shell stores each command in the history list prior to 


- 


parameter and variable expansion (see “Expansion,” earlier in this manual page) but after history expansion is performed, 
subject to the values of the shell variables command_oriented_history and HISTCONTROL. On startup, the history is initialized 
from the file named by the variable HisTFILe (default ~/.bash_history). HISTFILE is truncated, if necessary, to contain no 
more than HISTFILESIZE lines. T he built-in command fc (see Shell Built-in Commands, later in this manual page) may be 
used to list or edit and re-execute a portion of the history list. The history builtin can be used to display the history list and 
manipulate the history file W hen using the command-line editing, search commands are available in each editing mode that 
provide access to the history list. W hen an interactive shell exits, the last Hrsts1ze lines are copied from the history list to 
HISTFILE. If HISTFILE iS unset, or if the history file is unwritable, the history is not saved. 


HISTO RY EXPANSION 


The shal supports a history expansion feature that is similar to the history expansion in csh. This section describes what 
syntax features are available T his feature is enabled by default for interactive shells, and can be disabled using thex option to 
the set built-in command. (See “Shad Built-in Commands,” later in this manual page.) N oninteractive shells do not perform 
history expansion. 

History expansion is performed immediately after a complete line is read, before the shell breaks it into words. It takes place 
in two parts. The first isto determine which line from the previous history to use during substitution. The second is to sdect 
portions of that line for inclusion into the current one. T heline selected from the previous history is the event, and the 
portions of that line that are acted upon are words. The line is broken into words in the same fashion as when reading input, 
so that several meta character- separated words surrounded by quotes are considered as one word. Only the backslash (\) and 
single quotes can quote the history escape character, which is ! by default. 


Theshdl allows control of the various characters used by the history expansion mechanism. (See the description of histchars 
under “Shall Variables,” earlier in this manual page.) 


EVENT DESIGNATORS 
An event designator is a reference to a command line entry in the history list. 


! Start a history substitution, except when followed by a blank, newline, =, or (. 
1! Refer to the previous command. This isasynonym for !-1. 


In Refer to command linen. 
t—n Refer to the current command line minusn. 
Istring Refer to the most recent command starting with string. 
!2string [2] Refer to the most recent command containing string. 
“stringl “string2* Quick substitution. Repeat the last command, replacing string with string2. Equivalent to !!:s/ 
stringl /string2/. (See “M odifiers,” later in this manual page.) 
\# The entire command line typed so far. 
WORD DESIGNATORS 


A colon (:) separates the event specification from the word designator. It can be omitted if the word designator begins with a 
*, $, *, or . Words are numbered from the beginning of the line, with the first word being denoted by ao (zero). 


0 (zero) The zeroth word. For the shal, thisis the command word. 

n Thenth word. 

‘ The first argument. T hat is, word 1. 

$ The last argument. 

% The word matched by the most recent ?string? search. 

x-y A range of words; -y abbreviates o-y. 

* All of the words but the zeroth. This isa synonym for 1-$. lt isnot an error to use « if there is just 
one word in the event; the empty string is returned in that case 

x* Abbreviates x-$. 


xX- Abbreviates x-$ like x*, but omits the last word. 
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MODIFIERS 
After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a: 


h Remove a trailing pathname component, leaving only the head. 

r Remove a trailing suffix of the form .xxx, leaving the basename. 

Remove all but the trailing suffix. 

Remove all leading pathname components, leaving the tail. 

Print the new command but do not execute it. 

Quote the substituted words, escaping further substitutions. 

Quote the substituted words as with gq, but break into words at blanks and newlines. 

s/old/new/ Substitute new for the first occurrence of oi d in the event line Any delimiter can be used in place of 
/. Thefinal delimiter is optional if it is the last character of the event line T hedelimiter may be 
quoted in old and new with a single backslash. If 3 appears in new, it is replaced by oid. A single 
backslash will quote the a. 

& Repeat the previous substitution. 

g Cause changes to be applied over the entire event line. Thisisused in conjunction with :s (for 
example, :gs/ol d/new/) or :&.1f used with :s, any delimiter can be used in place of /, and the final 
ddimiter is optional if it is the last character of the event line. 


ARITHMETIC EVALUATION 


The shal allows arithmetic expressions to be evaluated, under certain circumstances. (See the 1et built-in command and 
“Arithmetic Expansion.”) Evaluation is done in long integers with no check for overflow, though division by 0 is trapped and 
flagged as an error. The following list of operators is grouped into levels of equal-precedence operators. The levels are listed 

in order of decreasing precedence. 


<x 2 BG + O@ 


bt Unary minus and plus 

es Logical and bitwise negation 
* 1% M ultiplication, division, renainder 
ae Addition, subtraction 

<< >> Left and right bitwise shifts 
<= >= Comparison 

ae Equality and inequality 

& Bitwise AND 

“ Bitwise exclusive or 

Bitwise or 

&& Logical ano 

I Logical or 

= ke [= %= $= -= <c= >>=Q="=!= Assignment 


Shel variables are allowed as operands; parameter expansion is performed before the expression is evaluated. T he value of a 
parameter is coerced to along integer within an expression. A shal variable need not have its integer attribute turned on to 
be used in an expression. 


Constants with a leading a are interpreted as octal numbers. A leading ox or ex denotes hexadecimal. O therwise, numbers 
take the form [base#]n, where base is a decimal number between 2 and 36 representing the arithmetic base, andn isa 
number in that base. If base isomitted, then base 10 is used. 


O perators are evaluated in order of precedence. Subexpressions in parentheses are evaluated first and may override the 
precedence rules. 


- 


SHELL BUILT-IN COMMANDS 


: [arguments ] No effect; the command does nothing beyond expanding arguments and performing 
any specified redirections. A zero exit code is returned. 

. filename [arguments ] Read and execute commands from fi! ename in thecurrent shall environment and 

source filename [arguments ] return the exit status of the last command executed from filename. If filename does 


not contain a slash, pathnamesin PATH are used to find the directory containing 
filename. The file searched for in PATH need not be executable. T he current directory 
is searched if no file is found in pat. If any arguments are supplied, they become the 
positional parameters when file is executed. O therwise, the positional parameters 
are unchanged. The return status is the status of the last command exited within the 
script (a if no commands are executed), and False if filenameis not found. 

alias [name[=value] ...] alias with no arguments prints the list of aliases in the form name=val ue on standard 
output. W hen arguments are supplied, an aliasis defined for each name whose value 
is given. A trailing space in value causes the next word to be checked for alias 
substitution when the alias is expanded. For each namein the argument list for 
which no value is supplied, the name and value of the alias is printed. alias returns 
True unless a name is given for which no alias has been defined. 

bg [jobspec] Placej obspec in thebackground, as if it had been started with a. If j obspec isnot 
present, the shell’s notion of the current job is used. bg jobspec returns 0 unless run 
whe job control is disabled or, when run with job control enabled, if jobspec was 
not found or started without job control. 





bind [-m keymap][-lvd][-q name] Display current readline key and function bindings, or bind a key sequence to a 
bind [-m keymap] -f filename readline function or macro. The binding syntax accepted is identical to that of 
bind [-m keymap] .inputrc, but each binding must be passed as a separate argument; for example, 
keyseq: function- name "\C-x\C-r": re-read-init-file. Options, if supplied, have the following meanings: 
-m keymap Usekeymap asthe keymap to be affected by the subsequent 


bindings. Acceptable keymap names are emacs, emacs-standard, 
emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. 
vi is equivalent to vi-command; emacs is equivalent to emacs - 


standard. 

-1 List the names of all read1ine functions. 

-v List current function names and bindings. 

-d Dump function names and bindings in such a way that they 
can be reread. 

-f filename Read key bindings from filename 

-q function Query about which keys invoke the named function. 


The return value is @ unless an unrecognized option is given or an error occurred. 

break [n] Exit from within a for, while, or until loop. If n is specified, break n levels. n must 
be1.Ifn is greater than the number of enclosing loops, all enclosing loops are 
exited. The return value is @ unless the shell is not executing aloop when break is 
executed. 


builtin shell-builtin [arguments ] Execute the specified shell builtin, passing it arguments, and return its exit status. 
This is useful when you wish to define a function whosenameis the same as a shdll 
builtin, but need the functionality of the builtin within the function itself. The ca 
builtin is commonly redefined this way. The return statusiSralse ifshel|-builtin is 
nota shell builtin command. 

cd [dir] Change the current directory to dir. The variable Home is the default dir. The 
variable cpPaTH defines the search path for the directory containing dir. Alternative 
directory names are separated by acolon (:). A null directory name in cppatu is the 
same as the current directory, that is, (.). If dir begins with a slash (/), then cppaTH is 


not used. An argument of - is equivalent to soLppwo. T hereturn value is True if the 
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directory was successfully changed; False otherwise. 


command [-pVv] command [arg ...] Run command with args suppressing the normal shall function lookup. O nly built- 
in commands or commands found in the patH are executed. If the -p option is given, 
the search for command iS performed using a default value for patH that is guaranteed 
to find all of the standard utilities. |f ether the -v or -v option is supplied, a 
description of command is printed. T he -v option causes a single word indicating the 
command or pathname used to invoke command to be printed; the -v option 
produces a more verbose description. An argument of — disables option checking for 
the rest of the arguments. If the -v or -v option is supplied, the exit status is 0 if 
command was found, and 1 if not. If neither option is supplied and an error occurred 
Or command Cannot be found, the exit status is 127. O therwise, the exit status of the 
command builtin is the exit status of command. 

continue [n] Resume the next iteration of the enclosing for, while, Or until loop. If n is specified, 
resume at the nth enclosing loop. » must be 1. If n is greater than the number of 
enclosing loops, the last enclosing loop (the top-levd loop) is resumed. The return 
value is @ unless the shell is not executing a loop when continue is executed. 


declare [-frxi] [name [=val ve]] D eclare variables and/or give them attributes. If no names are given, then display the 
typeset [-frxi][name [=value]] values of variables instead. T he options can be used to restrict output to variables 
with the specified attribute. 
-f Use function names only. 
-r M ake names read-only. T hese names cannot then be assigned 
values by subsequent assignment statenents. 
-x M ark names for export to subsequent commands via the 
environment. 
-i The variable is treated as an integer; arithmetic evaluation (see 


“Arithmetic Evaluation”) is performed when the variable is 
assigned a value. 


Using + instead of - turns off the attribute instead. W hen used in afunction, makes 
names local, as with the 1ocal command. The return value is o unless an illegal 
option is encountered, an attempt ismade to define a function using"-f foo=bar", 
one of the names is not a legal shell variable name, an attempt is made to turn off 
read-only status for a read-only variable, or an attempt is made to display a 
nonexistent function with -F. 


dirs [-l][+/-n] Display the list of currently renembered directories. Directories are added to the list 
with the pushd command; the popd command moves back up through thelist. 

+n Displays the nth entry counting from the left of the list shown 
by dirs when invoked without options, starting with zero. 

-n Displays the nth entry counting from the right of the list 
shown by dirs when invoked without options, starting with 
ze. 

-1 Produces a longer listing; the default listing format uses a tilde 


to denote the home directory. 


The return value is @ unless an illegal option is supplied or n indexes beyond the end 
of the directory stack. 

echo [-neE][arg ...] Output the args, separated by spaces. The return status is always 0. If -n is specified, 
the trailing newline is suppressed. If the -e option is given, interpretation of the 
following backslash-escaped characters is enabled. The -e option disables the 
interpretation of these escape characters, even on systems where they are interpreted 
by default. 


enable [-n][-all][name ...] 


eval [arg ...] 


exec [[-] command [arguments ]] 


exit [n] 


export [-nf][name[=word]] ... 
export -p 


fc [-e ename][-nlr] [first ][last ] 
fo -s [pat=rep][cmd ] 
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\a Alert (bell) 

\b Backspace 

\c Suppress trailing newline 

\f Form feed 

\n N ewline 

\r Carriage return 

\t H orizontal tab 

\v Vertical tab 

\\ Backslash 

\nnn Thecharacter whose ASCII codeisnnn (octal) 


Enable and disable builtin shell commands. T his allows the execution of a disk 
command that has the same nameas a shell builtin without specifying a full 
pathname. If -n is used, each name is disabled; otherwise, names are enabled. For 
example, to use the test binary found via the patH instead of the shell builtin version, 
type enable -n test. If no arguments are given, alist of all enabled shal builtinsis 
printed. If only -n issupplied, alist of all disabled builtins is printed. If only -a11 is 
supplied, thelist printed includes all builtins, with an indication of whether or not 
each is enabled. enable accepts -a asa synonym for -a11. The return value is @ unless 
anameisnot a shell builtin. 


The args are read and concatenated together into a single command. This command 
is then read and executed by the shall, and its exit status is returned as the value of 
the eval command. If there are no args, or only null arguments, eval returns True. 


If command is specified, it replaces the shal. N o new process is created. The arguments 
become the arguments to command. If the first argument is -, the shell places a dash in 
the zeroth arg passed to command. T hisis what login does. If the file cannot be 
executed for some reason, a noninteractive shell exits, unless the shell variable 
no_exit_on failed _exec exists, in which caseit returns failure. An interactive shal 
returns failure if the file cannot be executed. If command isnot specified, any 
redirections take effect in the current shell, and the return status iso. 


Cause the shell to exit with a status of n. If n isomitted, the exit status is that of the 
last command executed. A trap on exit is executed before the shell terminates. 


The supplied names are marked for automatic export to the environment of 
subsequently executed commands. If the -F option is given, the names refer to 
functions. If no names are given, or if the -p option is supplied, a list of all names 
that are exported in this shal is printed. T he -n option causes the export property to 
be removed from the named variables. An argument of — disables option checking 
for the rest of the arguments. export returnsan exit status of @ unless an illegal 
option is encountered, one of the names is not a legal shell variable name, or -f is 
supplied with a name that is not a function. 

Fix command. In the first form, arangeof commands from first tol ast is selected 
from the history list. first and!ast may be specified as a string (to locate the last 
command beginning with that string) or asa number (an index into the history list, 
where a negativenumber is used as an offset from the current command numba). If 
last iSnot specified, it is set to the current command for listing (so that fc -1 

-10 prints the last 10 commands) and to first otherwise. If first isnot specified, it 
is set to the previous command for editing and -16 for listing. 

The -n flag suppresses the command numbers whe listing. T he -r flag reverses the 
order of the commands. If the -1 flag is given, the commands are listed on standard 
output. O therwise the editor given by ename isinvoked on a file containing those 
commands. If ename iSnot given, the value of the Fcep1T variable is used, and the 
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fg [jobspec] 


getopts optstring name [args] 


hash [-r][name] 


help [pattern] 


value of ep1Tor if FceprT is not set. If neither variable is set, vi is used. W hen editing 
is complete, the edited commands are echoed and executed. 

In the second form, command is reexecuted after each instance of pat is replaced by 
rep. A useful alias to use with thisis r=fc -s, so that typing r cc runs the last 
command beginning with cc and typing r reexecutes the last command. 

If the first form is used, the return value iso unless an illegal option is encountered 
Orfirst Orlast specify history lines out of range. If the -e option is supplied, the 
return value is the value of the last command executed or failure if an error occurs 
with the temporary file of commands. If the second form is used, the return status is 
that of the command reexecuted, unless cma does not specify a valid history line, in 
which case fc returns failure. 


Placej obspec in the foreground, and make it the current job. Ifj obspec isnot 
present, the shell’s notion of the current job is used. The return value is that of the 
command placed into the foreground, or failure if run when job control is disabled 
or, when run with job control enabled, if j obspec does not specify a valid job or 
jobspec Specifies ajob that was started without job control. 

getopts is used by shell procedures to parse positional parameters. opt string contains 
the option letters to be recognized; if a letter is followed by acolon, the option is 
expected to havean argument, which should be separated from it by whitespace. 
Each time it isinvoked, getopts places the next option in the shell variablename, 
initializing name if it does not exist, and the index of the next argument to be 
processed into the variable opTIND. oPTIND iSinitialized to 1 each time the shdl ora 
shell script is invoked. When an option requires an argument, getopts places that 
argument into the variable optarc. The shell does not reset optinp automatically; it 
must be manually reset between multiple calls to getopts within thesame shdl 
invocation if anew set of parameters is to be used. 

getopts can report errors in two ways. If the first character of opt string iSacolon, 
silent error reporting is used. In normal operation, diagnostic messages are printed 
when illegal options or missing option arguments are encountered. If the variable 
OPTERR is set to 0, no error message will be displayed, even if the first character of 
optstring isnot acolon. 

If an illegal option is seen, getopts places a question mark (?) into name and, if not 
silent, prints an error message and unsets optarG. If getopts is silent, the option 
character found is placed in op-Tara and no diagnostic message is printed. 

If a required argument is not found, and getopts isnot silent, a question mark (2) is 
placed in name, OPTARG isunset, and a diagnostic message is printed. If getopts is 
silent, then acolon (:) is placed in name and optare is set to the option character 
found. 

getopts normally parses the positional parameters, but if more arguments are given 
in args, getopts parses those instead. getopts returns True if an option, specified or 
unspecified, is found. It returns False if the end of options is ercountered or an error 
Occurs. 

For each name, the full pathname of the command is determined and renembered. 
The -r option causes the shell to forget all renenbered locations. If no arguments 
are given, information about ranembered commands is printed. An argument of — 
disables option checking for the rest of the arguments. The return status is True 
unless aname is not found or an illegal option is supplied. 

Display helpful information about built-in commands. If pattern is specified, help 
gives detailed help on all commands matching pattern; otherwise, alist of the 
builtins is printed. The return status is @ unless no command matches pattern. 


history [n] 
history -rwan [filename ] 


jobs [-lnp][jobspec ... ] 
jobs -x command [ args ... ] 


kill [-s sigspec | -sigspec] 
[pid | jobspec] ... 
kill -1 [si gnum] 


let arg [arg ...] 


local [name[=value] ...] 


logout 
popd [+/-n] 
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With no options, display the command history list with line numbers. Lines listed 
with a* have been modified. An argument of n lists only thelastn lines. Ifa 
nonoption argument is supplied, it is used as the name of the history file if not, the 
value of HISTFILE is used. Options, if supplied, have the following meanings: 


-a Append the “new” history lines (history lines entered since the 
beginning of the current bash session) to the history file 
-n Read the history lines not already read from the history file 


into the current history list. T hese are lines appended to the 
history file since the beginning of the current bash session. 
-r Read the contents of the history file and use them asthe 
current history. 
w- W rite the current history to the history file, overwriting the 
history file’s contents. 


The return value is @ unless an illegal option is encountered or an error occurs while 
reading or writing the history file. 
The first form lists the active jobs. T he -1 option lists process !D sin addition to 
the normal information; the -p option lists only the process|D of the job’s process 
group leader. T he -n option displays only jobs that have changed status since last 
notified. If j obspec is given, output is restricted to information about that job. The 
return statusis @ unless an illegal option is encountered or an illegal j obs pec is 
supplied. 
If the -x option is supplied, jobs replaces anyj obspec found in command Orargs with 
the corresponding process group |D , and executes command, passing it args, returning 
its exit status. 
Send the signal named by sigspec to the processes named by pid Orj obspec. si gspec 
is either a signal name such as sIGKILL or asignal number. If si gspec isa signal 
name, the nameis not case sensitive and may be given with or without the sia 
prefix. If sigspec isnot present, then steTerm is assumed. An argument of -1 liststhe 
signal names. If any arguments are supplied when -1 is given, thenames of the 
specified signals are listed, and thereturn status is @. An argument of — disables 
option checking for the rest of the arguments. kill returns True if at least one signal 
was successfully sent, or False if an error occursor an illegal option is evcountered. 
Each arg isan arithmetic expression to be evaluated. (See “Arithmetic Evaluation.”) 
If the last arg evaluates to 0, let returns 1; 0 isreturned otherwise. 
For each argument, create a local variable named name, and assign itvalue. When 
local is used within a function, it causes the variable name to have a visible scope 
restricted to that function and its children. With no operands, local writes a list of 
local variables to the standard output. It is an error to use local when not within a 
function. The return status is @ unless local iS used outside a function, or an illegal 
nameis supplied. 
Exit alogin shell. 
Removes entries from the directory stack. W ith no arguments, renoves the top 
directory from the stack, and performs aca to the new top directory. 
+n Removes the nth entry counting from the left of the list shown 
by dirs, starting with zero. For example, popd +o removes the 
first directory, popa +1 the second. 
-n Removes the nth entry counting from the right of the list 
shown by dirs, starting with zero. For example, popd -o 
removes the last directory, popd -1 the next to last. 
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pushd [dir] pushd +/-n 


pwd 


read [-r][name ...] 


readonly [-f][name ...] 
readonly -p 


return [n] 


set [—abefhkmnptuvxldCHP] 
[-o option][arg ...] 


If the popd command is successful, a dirs is performed as well, and the return status 
iS@. popd returns False if an illegal option is encountered, the directory stack is 
empty, a nonexistent directory stack entry is specified, or the directory change fails. 
Adds a directory to the top of the directory stack, or rotates the stack, making the 
new top of the stack the current working directory. With no arguments, exchanges 
the top two directories and returns, unless thedirectory stack is empty. 


+n Rotates the stack so that the nth directory (counting from the 
left of the list shown by dirs) is at the top. 

-n Rotates the stack so that the nth directory (counting from the 
right) is at the top. 

dir Adds dir to the directory stack at the top, making it the new 


current working directory. 


If the pushd command is successful, a dirs is performed as well. If the first form is 
used, pushd returns unless the cd to dir fails. With the second form, pushd returns 0 
unless the directory stack isempty, a nonexistent directory stack element is specified, 
or the directory change to the specified new current directory fails. 


Print the absolute pathname of the current working directory. The path printed 
contains no symbolic links if the -p option to the set builtin command is set. (See 
also the description of nolinks under “Shall Variables,” earlier in thismanual page) 
The return status is @ unless an error occurs while reading the pathname of the 
current directory. 

Onelineisread from the standard input, and the first word is assigned to the first 
name, the second word to the second name, and so on, with leftover words assigned 
to the last name. Only the characters in 1Fs are recognized as word ddimiters. If no 
names are supplied, the line read is assigned to the variable repLy. The return codeis 
zero, unless end-of-file is encountered. If the -r option is given, a backslash-newline 
pair isnot ignored, and the backslash is considered to be part of theline. 


Thegiven names are marked readonly and the values of these names may not be 
changed by subsequent assignment. If the -f option is supplied, the functions 
corresponding to the names are so marked. If no arguments are given, or if the 

-p option is supplied, alist of all readonly namesis printed. An argument of — 
disables option checking for the rest of the arguments. The return status is@ unless 
an illegal option is encountered, one of thenames is not a legal shell variable name, 
or -f is supplied with aname that is not a function. 

Causes a function to exit with the rdurn value specified byn. If n isomitted, the 
return status is that of the last command executed in the function body. If used 
outside a function, but during execution of a script by the . (source) command, it 
causes the shell to stop executing that script and return dither n or the exit status of 
the last command executed within the script as the exit status of the script. If used 
outside a function and not during execution of a script by (. , thereturn status is 
False. 


-a Automatically mark variables that are modified or created for 
export to the environment of subsequent commands. 
-b Cause the status of terminated background jobs to be reported 


immediately, rather than before the next primary prompt. 
(Also see notify under “Shall Variables.”) 

-e Exit immediately if a simple command (see “Shel Grammar,” 
earlier in this manual page) exits with a non-zero status. The 
shell does not exit if the command that fails is part of an unti1 


bash 


Or while loop, part of an if statement, part of a 3a or |! list, or 
if the command's return value is being inverted via!. 

=f Disable pathname expansion. 

-h Locate and renenber function commands as functions are 
defined. Function commands are normally looked up when 
the function is executed. 


-k All keyword arguments are placed in the environment for a 
command, not just those that precede the command name. 
-m M onitor mode Job control is enabled. T his flag is on by 


default for interactive shals on systems that support it. (See 
“Job Control,” earlier in this manual page.) Background 
processes run in a separate process group and aline containing 
their exit status is printed upon ther completion. 


-n Read commands but do not execute them. T his may be used 
to check a shell script for syntax errors. Thisis ignored for 
interactive shells. 


-o option-name Th@option-name can be oneof the following: 
allexport— Same as -a. 


braceexpand— T he shal performs brace expansion. (See “Brace 
Expansion,” earlier in this manual page) This is on by default. 


emacs— Use an emacs-style command line editing interface 
This is enabled by default when the shell isinteractive unless 
the shell is started with the -nolineediting option. 


errexit— Same aS -e. 
histexpand— Same as -H. 


ignoreeof— T he effect is asif the shal command 
'TGNOREEOF=10' had been executed. (See “Shell V ariables.”) 


interactive-comments— Allow aword beginning with # to 
cause that word and all remaining characters on that line to be 
ignored in an interactive shell. (See “Comments,” earlier in 
this manual page.) 


monitor— Same as -m. 

noclobber— Same as -c. 

noexec— Same as -n. 

noglob— Same as -f. 

nohash— Same as -d. 

notify— Same as -b. 

nounset— Same as -u. 

physical— Same as -P. 

posix— Change the behavior of bash where the default 


operation differs from the PO SIX 1003.2 standard to match 
the standard. 


privileged— Same a -p. 

verbose— Same as -v. 

vi—Usea vi-style command line editing interface. 
xtrace— Same as -x. 


If NO option-name iS Supplied, the values of the current options 
are printed. 
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shift [n] 


suspend [-f] 


-p Turn on privileged mode. In this mode, the senv file isnot 
processed, and shal functions are not inherited from the 
environment. This is enabled automatically on startup if the 
effective user (group) ID isnot equal to the real user (group) 
ID. Turning this option off causes the effective user and group 
ID s to be set to the real user and group IDs. 

-t Exit after reading and executing onecommand. 

-u T reat unset variables as an error when performing parameter 
expansion. If expansion is attempted on an unset variable, the 
shell prints an error message, and, if not interactive, exits with 
a non-zero status. 

-v Print shell input lines as they are read. 

-x After expanding each simple command, bash displays the 
expanded value of ps4, followed by the command and its 
expanded arguments. 


-1 Save and restore the binding of name in afor name [in word] 
command. (See “Shell Grammar,” earlier in this manual page.) 
-d Disable the hashing of commands that are looked up for 


execution. Normally, commands are remenbered in a hash 
table, and once found, do not have to be looked up again. 


-C The effect is as if the shell command noclobber= had been 
executed. (See “Shell V ariables.”) 

-H Enable ! style history substitution. T his flag is on by default 
when theshal is interactive 

-P If set, do not follow symbolic links when performing 


commands such as cd that change the current directory. The 
physical directory is used instead. 

- If no arguments follow this flag, then the positional parameters 
are unset. O therwise, the positional parameters are set to the 
args, even if some of them begin with a-. 

- Signal the end of options, cause all remaining args to be 
assigned to the positional parameters. T he -x and -v options 
are turned off. If there are no args, the positional parameters 
remain unchanged. 

The flags are off by default unless otherwise noted. U sing + 
rather than - causes these flags to be turned off. The flags can 
also be specified as options to an invocation of the shell. The 
current set of flags may be found in $-. After the option 
arguments are processed, the renainingn args are treated as 
values for the positional parameters and are assigned, in order, 
to $1, $2, ... $n. If no options or args are supplied, all shall 
variables are printed. The return status is always True unless an 
illegal option is encountered. 


The positional parameters from n+1 ... arerenamed to .... Parameters represented 
by the numbers s# down to $#-n+1 are unset. If n is @, no parameters are changed. If 
nis not given, it isassumed to be 1. n must be a non-negative number less than or 
equal to $4. If n is greater than $#, the positional parameters are not changed. The 
return status is greater than 0 ifn is greater than or less than 9; otherwise o. 

Suspend the execution of this shell until it receives a s1@-cont signal. The -¢ option 
says not to complain if thisis a login shal; just suspend anyway. The return status is 
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@ unless the shell isa login shell and -f isnot supplied, or if job control is not 
enabled. 

test expr[expr] Return a status of 0 (True) or 1 (False) depending on the evaluation of the 
conditional expression expr. Expressions may be unary or binary. U nary expressions 


are often used to examine the status of a file There are string operators and numeric 
comparison operators as wal. Each operator and operand must be a separate 
argument. If file is of the form /dev/fd/n, then file descriptor n is checked. 

-b file—Trueiffile exists and is block special. 

-c file—True if file exists and is character special. 

-d file—True if file exists and isa directory. 

-e file—Trueiffile exists. 

-f file—Trueiffile exists and isa regular file. 

-g file—Trueif file exists and is set-group-id. 

-k file—Trueif file hasits “sticky” bit set. 

-L file—True if file exists and isa symbolic link. 

-p file—Trueiffile exists and isa named pipe. 

-r file—True if file exists and is readable. 

-s file—Trueif file exists and has a size greater than zero. 

-S file—True iffile exists and isa socket. 

-t fd—True if fd isopened on a terminal. 

-u file—Trueif file exists and its set-user-id bit is set. 

-w file—Trueiffile exists and is writable. 

-x file—Trueiffile exists and is executable. 

-0 file—True if file exists and is owned by the effective user ID. 

-G file—Trueif file exists and is owned by the effective group ID. 























filel -nt file2—True iffile1 isnewer (according to modification date) than 
file2. 


filel -ot file2—True if file1 isolder than file2. 


filel -ef file—True iffilel andfile2 havethe same device and inode 
numbers. 


-z string— True if the length of string is zero. 

-n string— True if the length of string isnon-zero. 

stringl = string2— True if the strings are equal. 

stringl != string2— True if the strings are not equal. 

! expr—True if expr iSFalse. 

exprl -a expr2—True if both expr1 AND expr2 are True. 

exprl -o expr2— True if either expr1 OR expr2 iS True. 

argl OP arg2 OP iSOne Of -eq, -ne, -1t, -le, -gt, OF -ge. These arithmetic binary 
operators return True if arg1 is equal, not-equal, less-than, less-than-or-equal, 
greater-than, or greater-than-or-equal than arg2, respectively. Arg1 and arg2 may 
be positive integers, negative integers, or the special expression -1 string, which 
evaluates to the length of string. 





times Print the accumulated user and system times for the shell and for processes run from 
the shell. The return status is 0. 
trap [-l][arg][sigspec] The command arg isto be read and executed when the shell receives signal(s) 


sigspec. If arg isabsent or -, all specified signals are reset to thar original values (the 
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type [-all][-type | -path] 
name [name ...] 


ulimit [-SHacdfmstpnuv [li mit ]] 


values they had upon entrance to the shell). If arg isthe null string, this signal is 
ignored by the shal and by the commands it invokes. si gspec iseither asignal name 
defined in <signal.h>, or asignal numbe™. If sigspec iSEXIT (0), the command arg 
is executed on exit from the shell. With no arguments, trap prints the list of 
commands associated with each signal number. T he -1 option causes the shell to 
print a list of signal names and ther corresponding numbers. An argument of — 
disables option checking for the rest of the arguments. Signals ignored upon entry to 
the shell cannot be trapped or reset. T rapped signals are reset to their original values 
in achild process when it is created. The return status is False if either the trap name 
or number is invalid; otherwise, trap returns True. 


W ith no options, indicate how each name would be interpreted if used as a 
command name. If the -type flag is used, type prints a phrase that is one of alias, 
keyword, function, builtin, OF file if name isan alias, shell reserved word, function, 
builtin, or disk file, respectively. If the name is not found, then nothing is printed, 
and an exit status of False is returned. If the -path flag is used, type either returns 
thename of the disk file that would be executed if name were specified asa command 
name, or nothing if -type would not return file. If a command is hashed, -path 
prints the hashed value, not necessarily the file that appears first in paTH. If the -a11 
flag is used, type prints all of the places that contain an executable named name. T his 
includes aliases and functions, if and only if the -path flag is not also used. The table 
of hashed commands is not consulted when using -a11. type accepts -a, -t, and -pin 
place of -a11, -type, and -path, respectively. An argument of — disables option 
checking for the rest of the arguments. type returns True if any of the arguments are 
found, False if none are found. 

ulimit provides control over the resources available to the shell and to processes 
started by it, on systems that allow such control. The value of 1imit can be anumber 
in theunit specified for the resource, or the value unlimited. Thex and s options 
specify that the hard or soft limit is set for the given resource A hard limit cannot be 
increased onceit is set; a soft limit may be increased up to the value of the hard 
limit. If neither H nor s is specified, the command applies to the soft limit. If 1imit is 
omitted, the current value of the soft limit of the resource is printed, unless the H 
option is given. When more than one resource is specified, the 1imit name and unit 
is printed before the value. O ther options are interpreted as follows: 








-a All current limits are reported. 

-¢ Themaximum size of core files created. 

-d Themaximum size of a process's data segment. 

-f Themaximum size of files created by the shell. 

=m Themaximum resident set size. 

-s The maximum stack size. 

-t The maximum amount of cpu time in seconds. 

-p The pipe size in 512-byte blocks. (T his may not be set.) 

-n Themaximum number of open file descriptors. (M ost systens 
do not allow this value to be set, only displayed.) 

-u Themaximum number of processes availableto a single user. 

-v Themaximum amount of virtual memory available to the 
shell. 


An argument of — disables option checking for the rest of the arguments. I f 1imit is 
given, it is the new value of the specified resource (the -a option is display only). If 
no option is given, then -f is assumed. Values arein 1024-byte increments, except 
for -t, which isin seconds; -p, which isin units of 512-byte blocks; and -n and -u, 
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which are unscaled values. The return statusis @ unless an illegal option is encoun- 
tered, anon-numeic argument other than unlimited is supplied as limit, or an error 
occurs while setting a new limit. 

umask [-S][mode ] Theuser file-creation mask is set to mode. If mode begins with a digit, it is interpreted 
as an octal number; otherwise, it is interpreted as a symbolic mode mask similar to 
that accepted by chmod(1). If mode is omitted, or if the-s option is supplied, the 
current value of the mask is printed. T he -s option causes the mask to be printed in 
symbolic form; the default output isan octal number. An argument of — disables 
option checking for the rest of the arguments. T he return status is 0 if the mode was 
successfully changed or if no mode argument was supplied, and False otherwise. 


unalias [-a][name ...] Remove names from the list of defined aliases. If -a is supplied, all alias definitions 
are renoved. The return value is True unless a supplied name is not a defined alias. 
unset [-fv][name ...] For each name, remove the corresponding variable or, given the -F option, function. 


An argument of — disables option checking for the rest of the arguments. N ote that 
PATH, IFS, PPID, PS1, PS2, UID, and EUID Cannot be unset. If any of RANDOM, SECONDS, 
LINENO, OF HISTCMD are unset, they lose their special properties, even if they are 
subsequently reset. The exit status is True unless aname does not exist or isnon- 
unsettable. 


wait [n] W ait for the specified process and return its termination status. n may bea process 
ID or ajob specification; if ajob spec is given, all processes in that job’s pipdine are 
waited for. If n isnot given, all currently active child processes are waited for, and the 
return status is zero. If n specifies anonexistent process or job, the return status is 
127. O therwise the return status is the exit status of the last process or job waited 
for. 





INVOCATION 
A login shell is one whose first character of argument zero isa -, or one started with the -1ogin flag. 


An interactive shell is one whose standard input and output are both connected to terminals (as determined by isatty(3)), or 
onestarted with the -i option. ps1 isset and includes i if bash isinteractive, allowing a shell script or astartup file to test this 
state, 


Login shells: 

On login (subject to the -noprofile option): 
/etc/profile exists, source it. 

“/.bash_profile exists, source it, 

se if ~/.bash_login exists, source it, 

se if “/.profile exists, source it. 

n exit: 

“/.bash_logout exists, source it. 

on-login interactive shells: 

n startup (subject to the -norc and -rcfile options): 

“/.bashre exists, source it. 

on-interactive shells: 

n startup: 

the environment variable ENV is non-null, expand 

and source the file it names, as if the command 

[ "$ENV" ]; then . $ENV; fi 

had been executed, but do not use PATH to search 

for the pathname. When not started in Posix mode, bash 
looks for BASH_ENV before ENV. 


a 
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If Bash is invoked as sh, it tries to mimic the behavior of sh as closdy as possible. For alogin shell, it attempts to source only / 
etc/profile and ~/.profile, in that order. The-noprofile option may still be used to disable this behavior. A shell invoked 
as sh does not attempt to source any other startup files. 
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When bash is started in posix mode, as with the -posix command line option, it follows the PO SIX standard for startup files. 
In this mode, the env variable is expanded and that file sourced; no other startup files are read. 
SEE ALSO 
Bash Features Brian Fox and Chet Ramey 
TheGnu Readline Library, Brian Fox and Chet Ramey 
TheGnu Higory Library, Brian Fox and Chet Ramey 
A System V Compatible | mplementation of 4.2BSD Job Control, D avid Lennet 
Portable O perating Sytem | nterface(PO SIX) Part 2: Shell and Utilities IEEE 
sh(1), ksh(1), csh(1), emacs(1), vi(1) readiine(3) 


FILES 
/bin/bash The bash executable 
/etc/profile The systemwide initialization file executed for login shdls 
/.bash_profile The personal initialization file, executed for login shells 
/.bashre Theindividual per-interactive-shell startup file 
/.inputre Individual readiine initialization file 

AUTHORS 


Brian Fox (Free Software Foundation; primary author; bfox@ai.mIT.Edu), Chet Ramey (Case Western Reserve U nivessity; 
chet@ins. CWRU. Edu) 


COPYRIGHT 
Copyright © 1989, 1991 by the Free Software Foundation, Inc. 


BUG REPORTS 


If you find a bug in bash, you should report it. But first, you should make sure that it really isa bug, and that it appears in 
the latest version of bash that you have 


Once you have determined that a bug actually exists, mail a bug report to bash-maintainers@prep.ai.M IT .Edu. If you havea 
fix, you are welcome to mail that as well! Suggestions and “philosophical” bug reports may be mailed to bug- 
bash@prep.ai.MIT.Edu or posted to the U senet newsgroup gnu.bash. bug. 


ALL bug reports should include the following: 


The version number of bash 

The hardware and operating system 

The compiler used to compile 

A description of the bug behavior 

A short script or “recipe” that exercises the bug 


Comments and bug reports concerning this manual page should be directed to chet@ins.cwru.edu. 


BUGS 
It's too big and too slow. 
There are some subtle differences between bash and traditional versions of sh, mostly because of the Posrx specification. 
Aliases are confusing in some uses. 
GNU, 9 March 1995 


befordi ght 
bdftopcf 


bdftopef— Convert X font from Bitmap D istribution Format to Portable C ompiled Format 


SYNOPSIS 


bdftopef [ -pn ][-un ][-m ][-1 ][-M ][-L ][-t ][-i ][-o outputfile ] fontfile.bdf 


DESCRIPTION 
bdftopef isa font compiler for the x server and font server. Fontsin Portable Compiled Format can be read by any 
architecture, although the file is structured to allow one particular architecture to read them directly without reformatting. 
This allows fast reading on the appropriate machine, but the files are still portable (but read more slowly) on other machines. 





OPTIONS 

=pn Sets the font glyph padding. Each glyph in the font will have each scanline padded in to amultiple 
of n bytes, wheren isl, 2, 4, or 8. 

-un Sets the font scanline unit. W hen the font bit order is different from the font byte order, the 
scanline unit n describes what unit of data (in bytes) are to be swapped; the unit i can be 1, 2, or 4 
bytes. 

=m Sets the font bit order to uss (most significant bit) first. Bits for each glyph will be placed in this 
order; that is, the leftmost bit on the screm will bein the highest valued bit in each unit. 

-1 Sets the font bit order to Ls (least significant bit) first. The leftmost bit on the screen will bein the 
lowest valued bit in each unit. 

-M Sets the font byte order to uss first. All multibyte data in the file (metrics, bitmaps, and everything 
else) will be written most significant byte first. 

-L Sets the font byte order to Lss first. All multibyte data in the file (metrics, bitmaps, and everything 
else) will be written least significant byte first. 

-t W hen this option is specified, bdftopct will convert fonts into taeminal fonts when possible A 





terminal font has each glyph image padded to the same size the x server can usually render these 
types of fonts more quickly. 


-i This option inhibits the normal computation of ink metrics. W hen a font has glyph images that do 
not fill the bitmap image (that is, the “on” pixds don’t extend to the edges of the metrics), battopct 
computes the actual ink metrics and places them in the pce file the -t option inhibits this behavior. 


-o output-file-name By default baftopct writes the pcr file to standard output; this option givesthe name of afileto be 
used instead. 


SEE ALSO 
x(1) 


AUTHOR 
Keith Packard, MIT X Consortium 


X Verdon 11 Reease 6 


beforelight 


beforelight— Screen saver 


SYNOPSIS 


beforelight [ -toolkitoption ... ] 
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DESCRIPTION 


The beforelight program is a sample implementation of a screen saver for x servers supporting the MIT -SCREEN- SAVER 
extension. 


AUTHORS 
Keith Packard (MIT X Consortium) 


X Verdon 11 Reease 6 


bif f 
bifft— Be notified if mail arrives and who it is from 


SYNOPSIS 


biff [ny] 


DESCRIPTION 
biff informsthe systen whether you want to be notified when mail arrives during the current terminal session. 
Options supported by bitf: 


n Disables notification 

y Enables notification 

W hen mail notification is enabled, the header and first few lines of the message will be printed on your screen whenever mail 
arrives. A 

biff y 


command is often included in the file .1ogin or .profile to be executed at each login. 
Biff operates asynchronously. For synchronous notification use the marL variable of sh(1) or the mail variable of csh(1). 


SEE ALSO 
esh(1), mail(1), sh(1), comsat(8) 


HISTORY 
The bitf command appeared in BSD 4.0. 
BSD 4, 14 March 1991 


bioradtopgm 


bioradtopgm— Convert a Biorad confocal file into a portable graymap 


SYNOPSIS 


bioradtopgm [ -image#][i magedata ] 


DESCRIPTION 


Reads a Biorad confocal file as input. Produces a portable graymap as output. If the resulting image is upside down, run it 
through pnmflip -tb. 
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OPTIONS 


- image# A Biorad image file may contain more than oneimage With this flag, you can specify which image to 
extract (only one at atime). The first image in the file has number zero. If no image number is supplied, 
only information about the image size and the number of images in the input is printed out. No output is 
produced. 


BUGS 


A Biorad image may bein word format. If Pbmpius isnot compiled with thesiacrays flag, word files cannot be converted. See 
the makefile. 


SEE ALSO 


pgm(5), pnmflip(1) 


AUTHORS 
Copyright © 1993 by O liver Trepte 
28 June1993 
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bitmap, bmtoa, atobm— Bitmap editor and converter utilities for the X Window Systen 


SYNOPSIS 

bitmap [ -options ...][filename ][basename ] 

bmtoa [ -chars ...][filename ] 

atobm [ -chars cc ][-name variable ][-xhot number ][-yhot number ][filename ] 
DESCRIPTION 


The bitmap program is a rudimentary tool for creating or editing rectangular images made up of 1s and Os. Bitmaps are used 
in x for defining clipping regions, cursor shapes, icon shapes, and tile and stipple patterns. 


The bmtoa and atobm filters convert bitmap files (FILE FormaT) to and from ASCII strings. They are most commonly used to 
quickly print out bitmaps and to generate versions for including in text. 
COMMAND-LINE OPTIONS 


Bitmap supports the standard X T oolkit command-line arguments; see x(1). T he following additional arguments are 
supported as well: 


-size WI DTHXHEI GHT Specifies size of the grid in squares. 

-sw dimension Specifies the width of squares in pixels. 

-sh dimension Specifies the height of squares in pixels. 

-gt dimension Grid tolerance If the square dimensions fall bdow the specified value, grid will be 
automatically turned off. 

-grid, +grid Turns on or off the grid lines. 

-axes, taxes Turns on or off the major axes. 

-dashed, +dashed Turns on or off dashing for the frame and grid lines. 


-stippled, +stippled Turns on or off stippling of highlighted squares. 
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-proportional, +proportional Turns proportional mode on or off. If proportional mode is on, square width is 
equal to square haght. If proportional modeis off, bitmap will use the smaller square 
dimension, if they were initially different. 

-dashes filename Specifies the bitmap to be used as a stipple for dashing. 

-stipple filename Specifies the bitmap to be used as a stipple for highlighting. 

-hl color Specifies the color used for highlighting. 

-fr color Specifies the color used for the frame and grid lines. 

filename Specifies the bitmap to be initially loaded into the program. If the file does not exist, 
bitmap will assumeit is a new file. 

basename Specifies the basename to be used in the C code output file. If it is different than the 


basename in the working file, bitmap will changeit when saving thefile 


bmtoa accepts the following option: 


-chars cc This option specifies the pair of characters to usein the string version of the bitmap. 
The first character is used for 0 bits and the second character is used for 1 bits. The 
default isto use dashes (-) for 0s and number signs (#) for 1s. 


atobm accepts the following options: 


-chars cc This option specifies the pair of characters to use when converting string bitmaps 
into arrays of numbers. The first character represents a 0 bit and the second 
character represents a 1 bit. T he default is to use dashes (-) for Os and number signs 
(#) for 1s. 

-name variable This option specifies the variable name to be used when writing out the bitmap file 
T he default is to use the basename of the filename command-line argument or leave 
it blank if the standard input is read. 


-xhot number This option specifies the X coordinate of the hot spot. O nly positive values are 
allowed. By default, no hot spot information is included. 
-yhot number This option specifies the Y coordinate of the hot spot. O nly positive values are 


allowed. By default, no hot spot information is included. 


USAGE 


bitmap displays grid in which each square represents a single bit in the picture being edited. Actual size of the bitmap image, 
as it would appear normally and inverted, can be obtained by pressing M etal. You are free to move the image pop-up out of 
the way to continue editing. Pressing the left mouse button in the pop-up window or M eta again will remove the real size 
bitmap image. 


If the bitmap is to be used for defining a cursor, one of the squares in the images may be designated as the hot spot. This 
determines where the cursor is actually pointing. For cursors with sharp tips (such as arrows or fingers), this is usually at the 
end of thetip; for symmetric cursors (such as crosses or bulls-eyes), this is usually at the center. 


Bitmaps are stored as small C code fragments suitable for including in applications. They provide an array of bits as well as 
symbolic constants giving the width, height, and hot spot (if specified) that may be used in creating cursors, icons, and tiles. 


EDITING 


To edit a bitmap image simply click on one of the buttons with drawing commands (Point, Curve, Line Rectangle, and so 
on) and move the pointer into the bitmap grid window. Press one of the buttons on your mouse and the appropriate action 
will take place. You can eather set, clear, or invert the grid squares. Setting a grid square corresponds to setting a bit in the 
bitmap image to 1. Clearing a grid square corresponds to setting a bit in the bitmap image to 0. Inverting a grid square 
corresponds to changing a bit in the bitmap image from o to 1 or 1 to @, depending what its previous state was. T he default 
behavior of mouse buttons is as follows: 
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MouseButton1 Set 

MouseButton2 Invert 
MouseButton3 Clear 
MouseButton4 Clear 
MouseButton5 Clear 


This default behavior can be changed by setting the button function resources. H ere is an example: 


bitmap*button1Function: Set 
bitmap*button2Function: Clear 
bitmap*button3Function: Invert 
etc. 


The button function applies to all drawing commands, including copying, moving and pasting, flood filling, and setting the 
hot spot. 


DRAWING COMMANDS 
H ereis the list of drawing commands accessible through the buttons at the left side of the application’s window. Some 
commands can be aborted by pressing A inside the bitmap window, allowing the user to select different guiding points where 
applicable. 


Clear This command clears all bits in the bitmap image. The grid squares will be set to the 
background color. Pressing C inside the bitmap window has the same effect. 

Set This command sets all bits in the bitmap image. The grid squares will be set to the 
foreground color. Pressing S inside the bitmap window has the same effect. 

Invert This command inverts all bits in the bitmap image T he grid squares will be inverted 
appropriately. Pressing | inside the bitmap window has the same effect. 

M ark This command is used to mark an area of the grid by dragging out a rectangular 


shape in the highlighting color. After the area is marked, it can be operated on by a 
number of commands (see Up, D own, Lett, Right, Rotate Flip, Cut, and so on). 
Only one marked area can be present at any time If you attempt to mark another 
area, the old mark will vanish. T he same effect can be achieved by pressing Shift- 

M ouseButton1 and dragging out a rectangle in the grid window. Pressing Shift- 

M ouseButton2 will mark the entire grid area. 


Unmark This command will cause the marked area to vanish. The same effect can be 
achieved by pressing Shift-M ouseB utton3. 
Copy This command is used to copy an area of the grid from one location to anothe. If 


there isno marked grid area displayed, Copy behaves just like M ark. O nce thereisa 
marked grid area displayed in the highlighting color, this command has two 
alternative behaviors. | f you click a mouse button inside the marked area, you will be 
able to drag the rectangle that represents the marked area to the desired location. 
After you release the mouse button, the area will be copied. If you click outside the 
marked area, C opy will assume that you wish to mark a different region of the 
bitmap image, thus it will behave like M ark again. 

Move This command is used to move an area of the grid from one location to another. Its 
behavior resembles the behavior of C opy command, except that the marked area will 
be moved instead of copied. 

Flip Horizontally This command will flip the bitmap image with respect to the horizontal axes. If a 
marked area of the grid is highlighted, it will operate only inside the marked area. 
Pressing H inside the bitmap window has the same effect. 

Up This command moves the bitmap image one pixel up. If a marked area of the grid is 
highlighted, it will operate only inside the marked area. Pressing U pArrow inside the 
bitmap window has the same effect. 
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Flip V ettically 
Left 

Fold 

Right 

Rotate L eft 
Down 

Rotate Right 


Point 
Curve 


Line 
Rectangle 


Filled Rectangle 


Circle 


Filled Circle 


Flood Fill 


This command will flip the bitmap image with respect to the vertical axes. If a 
marked area of the grid is highlighted, it will operate only inside the marked area. 
Pressing V inside the bitmap window has the same effect. 

This command moves the bitmap image one pixel to the left. If a marked area of the 
grid is highlighted, it will operate only inside the marked area. Pressing LetArrow 
inside the bitmap window has the same effect. 

This command will fold the bitmap image so that the opposite corners become 
adjacent. T his is useful when creating bitmap images for tiling. Pressing F inside the 
bitmap window has the same effect. 

This command moves the bitmap image one pixd to the right. If a marked area of 
the grid is highlighted, it will operate only inside the marked area. Pressing the right 
arrow inside the bitmap window has the same effect. 

This command rotates the bitmap image 90 degrees to the left (counter clockwise) 
If a marked area of the grid is highlighted, it will operate only inside the marked 
area. Pressing L inside the bitmap window has the same effect. 

This command moves the bitmap image one pixel down. If a marked area of the grid 
is highlighted, it will operate only inside the marked area. Pressing the down arrow 
inside the bitmap window has the same effect. 

This command rotates the bitmap image 90 degrees to the right (clockwise) If a 
marked area of the grid is highlighted, it will operate only inside the marked area. 
Pressing R inside the bitmap window has the same effect. 

This command will changethe grid squares underneath the mouse pointer if a 
mouse button is being pressed down. If you drag the mouse button continuously, 
the line may not be continuous, depending on the speed of your system and 
frequency of mouse motion events. 

This command will changethe grid squares underneath the mouse pointer if a 
mouse button is being pressed down. If you drag the mouse button continuously, it 
will make sure that the line is continuous. If your system is slow or bitmap receives 
very few mouse motion events, it might behave quite strangely. 

This command will changethe grid squares in a line between two squares. O nce you 
press a mouse button in the grid window, bitmap will highlight the linefrom the 
square where the mouse button was initially pressed to the square where the mouse 
pointer is located. By rdeasing the mouse button, you will cause the change to take 
effect, and the highlighted line will disappear. 

This command will changethe grid squares in a rectangle between two squares. 
Once you press a mouse button in the grid window, bitmap will highlight the 
rectangle from the square where the mouse button was initially pressed to the square 
where the mouse pointer is located. By releasing the mouse button you will cause the 
change to take effect, and the highlighted rectangle will disappear. 

This command is identical to Rectangle except at the end the rectangle will be filled 
rather than outlined. 

This command will change the grid squares in a circle between two squares. Once 
you press a mouse button in the grid window, bitmap will highlight the circle from 
the square where the mouse button was initially pressed to the square where the 
mouse pointer is located. By releasing the mouse button you will cause the change to 
take effect, and the highlighted circle will disappear. 

This command is identical to Circle except at the end the circle will be filled rather 
than outlined. 

This command will flood fill the connected area underneath the mouse pointer 
whe you click on the desired square. D iagonally adjacent squares are not considered 
to be connected. 
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Set H ot Spot This command designates one square in the grid as the hot spot if this bitmap image 
is to be used for defining a cursor. Pressing a mouse button in the desired square will 
cause a diamond shape to be displayed. 

Clear H ot Spot This command removes any designated hot spot from the bitmap image. 

Undo This command will undo the last executed command. It has depth one, that is, 
pressing Undo after U ndo will undo itself. 


FILE MENU 


The File menu commands can be accessed by pressing the File button and selecting the appropriate menu entry, or by 
pressing the Ctrl key with another key. T hese commands deal with files and global bitmap parameters, such as size, 
basename, filename, and so forth. 


N ew This command will clear the editing area and prompt for the name of the new file to 
be edited. It will not load in the new file 
Load This command is used to load a new bitmap file into the bitmap editor. If the 


current image has not been saved, user will be asked whether to save or ignore the 
changes. T he editor can edit only onefile at atime If you need interactive editing, 
run anumber of editors and use the cut and paste mechanism as described later in 
this section. (See “Cut and Paste”) 

Insert This command is used to insert a bitmap file into the image being currently edited. 
After bang prompted for the filerame, click inside the grid window and drag the 
outlined rectangle to the location where you want to insert the new file. 

Save This command will save the bitmap image. It will not prompt for the filename 
unless it is said to be <none>. If you leave the filename undesignated or -, the output 
will be piped to stdout. 





Save As This command will save the bitmap image after prompting for anew filerame. It 
should be used if you want to change the filename 
Resize This command is used to resize the editing area to the new number of pixels. The 


size should be entered in the widthl height format. The information in the image 
being edited will not be lost unless the new size is smaller that the current image size 
The editor was not designed to edit huge files. 

Rescale This command is used to rescale the editing area to the new width and haght. The 
size should be entered in the width] height format. It will not do antialiasing and 
information will be lost if you rescale to the smaller sizes. Fed free to add you own 
algorithms for better rescaling. 

Fileiame This command is used to change the filename without changing the basename nor 
saving the file. If you specify - for a filename, the output will be piped to stdout. 

Basename This command is used to change the basename if a different one from the specified 
filename is desired. 

Quit This command will terminate the bitmap application. If the file was not saved, user 
will be prompted and asked whether to save the image or not. Quit is preferred over 
killing the process. 





EDIT MENU 


The Edit menu commands can be accessed by pressing the Edit button and selecting the appropriate menu entry, or by 
pressing M eta key with another key. These commands deal with editing facilities such as grid, axes, Zooming, cut and paste, 
and so on. 


Image This command will display the image being edited and its inverse in its actual size in 
a separate window. T he window can be moved away to continue with editing. 
Pressing the left mouse button in the image window will cause it to disappear from 
the screen. 
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Grid This command controls the grid in the editing area. If the grid spacing is bdow the 
value specified by gridTolerance resource (8 by default), the grid will be automati- 
cally turned off. It can be enforced by explicitly activating this command. 


Dashed This command controls the stipple for drawing the grid lines. The stipple specified 
by dashes resource can beturned on or off by activating this command. 
Axes This command controls the highlighting of the main axes of the image being edited. 


The actual lines are not part of theimage. T hey are provided to aid use whan 
constructing symmetrical images, or whenever having the main axes highlighted 


hdps your editing. 

Stippled This command controls the stippling of the highlighted areas of the bitmap image. 
The stipple specified by stipple resource can be turned on or off by activating this 
command. 

Proportional This command controls the proportional mode If the proportional mode is on, 


width and haght of all image squares are forced to be equal, regardless of the 
proportions of the bitmap window. 

Zoom This command controls the zoom mode If there is a marked area of the image 
already displayed, bitmap will automatically zoom into it. O therwise, the user will 
have to highlight an area to be edited in the zoom mode and bitmap will automati- 
cally switch into it. You can use all the editing commands and othe utilities in the 
zoom mode. W hen you zoom out, undo command will undo the whole zoom 


session. 

Cut This commands cuts the contents of the highlighted image area into the internal cut 
and paste buffer. 

Copy This command copies the contents of the highlighted image area into the internal 
cut and paste buffer. 

Paste This command will check if there are any other bitmap applications with a 


highlighted image area, or if there is something in the internal cut and paste buffer 
and copy it to the image. T o place the copied image, click in the editing window and 
drag the outlined image to the position where you want to placei, and then rdease 
the button. 


CUT AND PASTE 


Bitmap supports two cut and paste mechanisms; the internal cut and paste and the global X selection cut and paste The 
internal cut and paste is used when executing copy and move drawing commands and also cut and copy commands from the 
Edit menu. The global X sdection cut and paste is used whenever there isa highlighted area of a bitmap image displayed 
anywhere on the scren. To copy apart of image from another bitmap editor, simply highlight the desired area by using the 
M ark command or pressing the shift key and dragging the area with the left mouse button. W hen the selected area becomes 
highlighted, any other applications (such as xterm) that use primary selection will discard their section values and 
unhighlight the appropriate information. N ow, use the Paste command from the Edit menu or control mouse button to 
copy the selected part of image into another (or the same) bitmap application. If you attempt to do this without a visible 
highlighted image area, the bitmap will fall back to the internal cut and paste buffer and paste whatever was stored there at 
the moment. 


WIDGETS 


Following is the widget structure of the bitmap application. T he widget class name is given first, followed by the widget 
instance name. All widgets except the bitmap widget are from the standard Athena widget set. 


Bitmap bitmap 
TransientShell image 
Box box 

Label normalImage 
Label invertedImage 
TransientShell input 


Command cance 
TransientShell error 
Dialog dialog 
Command abort 
Command retry 
TransientShell qsave 
Dialog dialog 
Command yes 
Command no 
Command cance 
Paned parent 
Form formy 
MenuButton fileButton 
SimpleMenu fileMenu 
SmeBSB new 

SmeBSB load 

SmeBSB insert 

SmeBSB save 

SmeBSB saveAs 

SmeBSB resize 

SmeBSB rescale 

SmeBSB filename 
SmeBSB basename 
SmeLine line 

SmeBSB quit 
MenuButton editButton 
SimpleMenu editMenu 
SmeBSB image 

SmeBSB grid 

SmeBSB dashed 

SmeBSB axes 

SmeBSB stippled 
SmeBSB proportional 
SmeBSB zoom 

SmeLine line 

SmeBSB cut 

SmeBSB copy 

SmeBSB paste 

Label status 

Pane pane 

Bitmap bitmap 

Form form 

Command clear 

Command set 

Command invert 

Toggle mark 

Command unmark 

Toggle copy 

Toggle move 

Command flipHoriz 
Command up 

Command flipVert 
Command left 

Command fold 

Command right 

Command rotateLeft 
Command down 

Command rotateRight 











bitmap, bmtoa, atobm 
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Toggle point 

Toggle curve 

Toggle line 

Toggle rectangle 
Toggle filledRectangle 
Toggle circle 

Toggle filledCircle 
Toggle floodFill 
Toggle setHotSpot 


Command clearHotSpot 


Command undo 


COLORS 


If you would like bitmap to be viewable in color, include the following in the #ifdet coLor section of the file you read with 


xrdb: 


*customization: 


This will cause bitmap to pick up the colors in the app-defaults color customization file 


<XRoot>/1ib/X11/app-defaults/Bitmap-color 


where <xRoot> refers to the root of the X11 install tree. 


BITMAP WIDGET 


Bitmap widget is a standalone widget for editing raster images. It is not designed to edit large images, although it may be 
used in that purpose as well. It can be freely incorporated with other applications and used as a standard editing tool. The 
following are the resources provided by the bitmap widget: 


H eader file 
Class 

Class N ame 
Superclass 


Bitmap.h 
bitmapWidgetClass 
Bitmap 

Bitmap 


All the Simple W idget resources plus... 





Name Class T ype D efault Value 
foreground Foreground Pixd XtD efaultForeground 
highlight Highlight Pixd XtD efaultForeground 
framing Framing Pixd XtD efaultForeground 
gridT olerance GridT olerance Dimension 8 

size Size String 32x32 

dashed Dashed Boolean True 

grid Grid Boolean True 

stippled Stippled Boolean True 

proportional Proportional Boolean True 

axes Axes Boolean False 

squareW idth SquareW idth Dimension 16 

squareH eight SquareH eight Dimension 16 

margin Margin Dimension 16 

XH ot XH ot Position N otSet (-1) 

yH ot YHot Position N otSet (-1) 
button1Function Button1Function D rawingFunction Set 


brushtopbm 





Name Class T ype D efault Value 
button2Function Button2F unction D rawingFunction Invert 
button3Function Button3F unction D rawingFunction Clear 
button4Function Button4F unction D rawingFunction Invert 
button5Function Button5F unction D rawingFunction Invert 
filename Filename String None (“") 
basename Basename String None (“") 
AUTHOR 

Davor M atic (MIT X Consortium) 

X Version 11 Redease 6 

bmptoppm 

bmptoppm— Convert aBM P file into a portable pixmap 
SYNOPSIS 

bmptoppm [bmpfile] 
DESCRIPTION 

bmptoppm reads a M icrosoft W indows or O S/2 BM P fileas input and produces a portable pixmap as output. 
SEE ALSO 

ppmtobmp(1), ppm(5) 
AUTHOR 


Copyright © 1992 by D avid W. Sanderson 
26 October 1992 


brushtopbm 


brushtopbm— C onvet a doodle brush file into a portable bitmap 


SYNOPSIS 


brushtopbm [brushfile] 


DESCRIPTION 
brushtopbm reads a Xerox doodle brush file as input and produces a portable bitmap as output. 
N ote that there is currently no pbmtobrush tool. 


SEE ALSO 
pbm(5) 


AUTHOR 
Copyright © 1988 by J ef Poskanzer 
28 August 1988 
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cal 


cal— Displays a calendar 


SYNOPSIS 
cal [-jy] [month [year ]] 
DESCRIPTION 
cal displays a simple calendar. If arguments are not specified, the current month is displayed. T he options are as follows: 
-j Display Julian dates (days one-based, numbered from J anuary 1) 
-y Display a calendar for the current year 


A single parameter specifies the year (1-9999) to be displayed; note the year must be fully specified: 
cal 89 


will not display a calendar for 1989. T wo parameters denote the month (1-12) and year. If no parameters are specified, the 
current month's calendar is displayed. 


A year starts on Jan 1. 


The Gregorian R eormation is assumed to have occurred in 1752 on the 3rd of September. By this time, most countries had 
recognized the reformation (although a few did not recognize it until the early 1900s.) Ten days following that date were 
eliminated by the reformation, so the calendar for that month is a bit unusual. 


HISTORY 
A cal command appeared in version 6 AT&T UNIX 


6 June1993 


cat 


cat— Concatenate files and print on the standard output 


SYNOPSIS 
cat [-benstuvAET] [—number] [—number-nonblank] [ —squeeze-blank] 
[—show-nonprinting] [—show-ends] [—show-tabs] [—show-all] 
[—help] [—version] [file...] 

DESCRIPTION 


This manual page documents the GN U version of cat. cat writes the contents of each given file, or the standard input if 
noneare given or whe afile named - is given, to the standard output. 


OPTIONS 
-b, —number-nonblank Numbe all nonblank output lines, starting with 1. 
-e Equivalent to -vE. 
-n, —number Numbe all output lines, starting with 1. 
-s, —squeeze-blank Replace multiple adjacent blank lines with a single blank line 
-t Equivalent to -vt. 


-u Ignored; for UNIX compatibility. 


chattr 


-v, —show-nonprinting Display control characters except for LFp and TaB using * notation and precede characters that 
have the high bit set with m-. 

-A, —show-all Equivalent to -ver. 

-E, —show-ends Display as after the end of each line 

-T, —show-tabs Display tab characters as *1. 

—help Print a usage message and exit with anonzero status. 

—version Print version information on standard output then exit. 
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chattr 


chattr— Change file attributes on a Linux second extended file system 


SYNOPSIS 
chattr [ -RV ][-v version ] [ mode ] files... 
DESCRIPTION 


chattr changes the files attributes on an second extended file system. T he format of asymbolic modeis+-=[Sacdisu]. 


The operator + causes the sdected attributes to be added to the existing attributes of the files; - causes them to be renoved; 
and = causes them to be the only attributes that the files have. T he letters sacdisu select the new attributes for the files: 
synchronous updates (s), append only (a), compressed (x), immutablei), nodump (d), secureddetion (s), and undeletable 
(u). 


OPTIONS 
-R Recursiveay change attributes of directories and thar contents. 
-V Verbosely describe changed attributes. 
-v version Se the file’s version. 

ATTRIBUTES 


A file with the a attribute set can only be open in append mode for writing. 


A file with the c attribute set is automatically compressed on the disk by the kernel. A read from this file returns 
uncompressed data. A write to this file compresses data before storing them on the disk. 


A file with the a attribute set is not candidate for backup when the dump(s) program isrun. 


A file with the i attribute cannot be modified: it cannot be deleted or renamed, no link can be created to this file and no data 
can be written to the file. O nly the superuser can set or clear this attribute. 


When a file with thes attribute set is ddeted, its blocks are zeroed and written back to the disk. 


When afile with theu attribute set is modified, the changes are written synchronously on the disk; this is equivalent to the 
syn' mount option applied to a subset of the files. 


When a file with theu attribute set is ddeted, its contents is saved. T his allows the user to ask for its undeletion. 
AUTHOR 


chattr has been written by Remy Card, <card@masi.ibp.fr>, the develope’ and maintainer of the ext2 fs. 
BUGS AND LIMITATIONS 

As of ext2 fs 0.5a, thec and u attributes are not honored by the kernel code 

T hese attributes will be implemented in a future ext2 fs version. 
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AVAILABILITY 


chattr iS available for anonymous ftp from ftp.ibp.fr and tsx-11.mit.edu iN /pub/linux/packages/ext2fs. 
SEE ALSO 
lsattr(1) 
Vergon 0.5b, N ovenber 1994 


chfn 


chfn— Change your finger information 


SYNOPSIS 
chfn [ -f full-name ][-o office][-p office-phone ] [ -h home-phone ] [ -u ] [ -v ] 
[username ] 

DESCRIPTION 


chfn iS used to change your finger information. Thisinformation is stored in the /etc/passwa file and is displayed by the 
finger program. The Linux finger command will display four pieces of information that can be changed by chfn: your real 
name, your work room and phone, and your home phone. 


COMMAND LINE 


Any of the four pieces of information can be specified on the command line. If no information is given on the command 
line, chfn enters interactive mode 


INTERACTIVE MODE 


In interactive mode, chfn will prompt for each fidd. At a prompt, you can enter the new information, or just press return to 
leave the field unchanged. Enter the keyword none to make the field blank. 


OPTIONS 
-f, —full-name Specify your real name. 
-0, —office Specify your office room number. 
-p, —office-phone Specify your office phone number. 
-h, —home- phone Specify your home phone number. 
-u, —help Print a usage message and exit. 
-v, —version Print version information and exit. 
SEE ALSO 
finger(1), passwd(5) 
AUTHOR 


Salvatore V alente (<svalente@mit .edu>) 
chfn, October 13 1994 


chmod 


chgrp 


chgrp— Change the group ownership of files 


SYNOPSIS 
chgrp [-Rcfv] [—recursive] [—changes] [—silent] [—quiet] [—verbose] [—help] 
[—version] group file... 

DESCRIPTION 


This manual page documents the GN U version of chgrp. chgrp changes the group ownership of each given file to the naned 
group, which can be athe a group nameor anumeric group ID. 


OPTIONS 
-c, —changes Verbosely describe only files whose ownership actually changes. 
-f, —silent, —quiet Do not print error messages about files whose ownership cannot be changed. 
-v, —verbose Verbosely describe ownership changes. 
-R, —recursive Recursiveay change ownership of directories and their contents. 
—help Print a usage message on standard output and exit successfully. 
—version Print version information on standard output, then exit successfully. 
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chkdupexe 


chkdupexe— Find duplicate executables 


SYNOPSIS 


chkdupexe 


DESCRIPTION 


chkdupexe Will Scan many standard directories that hold executable, and report duplicates. 


AUTHOR 
Nicolai Langfadt 


BUGS 
RequiresGNU 1s(1). 


Search paths that point to the same directory will cause many bogus duplicates to be found. You might want to edit the 
script to eliminate some paths that are equivalent on your machine 


11 March 1995 


chmod 


chmod— C hange the access permissions of files 


SYNOPSIS 


chmod [-Rcfv] [—recursive] [—changes] [—silent] [—quiet] [—verbose] [—help] 
[—version] mode file... 
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DESCRIPTION 


This manual page documents the GN U version of chmod. chmod changes the permissions of each given file according to mode, 
which can be either a symbolic representation of changes to make, or an octal number representing the bit pattern for the 
new permissions. 


The format of a symbolic modeis [ugoa...][[+-=][rwxXstugo...]...][,...]. Multiple symbolic operations can be given, 
separated by commas. 


A combination of the letters ugoa controls which users’ access to the file will be changed: the user who ownsit (u), other users 
in thefile’s group (g), other users not in the file's group (o), or all users (a). If none of these are given, the effect is as if a were 
given, but bits that are set in the umask are not affected. 


The operator + causes the permissions selected to be added to the existing permissions of each file - causes then to be 
removed; and = causes them to be the only permissions that the file has. 


The letters rwxxstugo select the new permissions for the affected users: read (r), write (w), execute (or access for directories) 
(x), execute only if thefile is a directory or already has execute permission for some user (x), set user or group ID on 
execution (s), save program text on swap device (t), the permissions that the user who owns the file currently has for it (u), 
the permissions that other users in the file's group have for it (g), and the permissions that other users not in the file’s group 
have for it (0). 


A numaic modeis from one to four octal digits (0-7), derived by adding up the bits with values 4, 2, and 1. Any omitted 
digits are assumed to be leading zeros. The first digit selects the set user 1D (4) and set group ID (2) and save text image (1) 
attributes. T he second digit selects permissions for the user who owns the file: read (4), write (2), and execute (1); the third 
selects permissions for other users in the file’s group, with the same values; and the fourth for other users not in thefile’s 
group, with the same values. 


chmod never changes the permissions of symbolic links; the chmod system call cannot change their permissions. Thisis not a 
problem since the permissions of symbolic links are never used. H owever, for each symbolic link listed on the command line, 
chmod Changes the permissions of the pointed-to file In contrast, chmod ignores symbolic links encountered during recursive 
directory traversals. 


OPTIONS 
-c, —changes Verbosely describe only files whose permissions actually change 
-f, —silent, —quiet Do not print error messages about files whose permissions cannot be changed. 
-v, —verbose Verbosely describe changed permissions. 
-R, —recursive Recursivey change permissions of directories and their contents. 
—help Print a usage message on standard output and exit successfully. 
—version Print version information on standard output, then exit successfully. 
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chown 


chown— C hange the user and group ownership of files 


SYNOPSIS 


chown [-Rcfv] [—recursive] [—changes] [—help] [—version] [—silent] [—quiet] 
[—verbose] [user][:.][group] file... 


DESCRIPTION 


This manual page documents the GN U version of chown. chown changes the user and/or group ownership of each given file, 
according to its first nonoption argument, which is interpreted as follows. If only a username (or numeric user ID ) is given, 
that user is made the owner of each given file and thefiles’ group is not changed. If the username is followed by a colon or 
dot and a group name (or numeric group |D ), with no spaces betwen then, the group ownership of the files is changed as 
well. If acolon or dot but no group name follows the username, that user is made the owner of the files and the group of the 
files is changed to that user’s login group. If the colon or dot and group are given, but the username is omitted, only the 
group of the files is changed; in this case, chown performs the same function as chgrp. 


OPTIONS 
-c, —changes Verbosely describe only files whose ownership actually changes. 
-f, —silent, —quiet Do not print error messages about files whose ownership cannot be changed. 
-v, —verbose Verbosely describe ownership changes. 
-R, —recursive Recursiveay change ownership of directories and their contents. 
—help Print a usage message on standard output and exit successfully. 
—version Print version information on standard output then exit successfully. 
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chsh 


chsh— Change your login shal 


SYNOPSIS 

chsh [ -s shell ] [ -1 ] [ -u ] [ -v ] [ username ] 
DESCRIPTION 

chsh iS used to change your login shal. If a shell is not given on the command line, chsh prompts for one 
VALID SHELLS 


chsh will accept the full pathname of any executable file on the system. H oweve,, it will issue a warning if the shell is not 
listed in the /etc/shells file 


OPTIONS 
-s, —shell Specify your login shal. 
-1, —list-shells Print the list of shells listed in /etc/shel1s and exit. 
-u, —help Print a usage message and exit. 
-v, —version Print version information and exit. 
SEE ALSO 
login(1), passwa(5), shel1s(5) 
AUTHOR 


Salvatore V alente (<svalente@mit .edu>) 
chsh, 13 October 1994 
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Cl 

ci— Check in RCS revisions 
SYNOPSIS 

ci [options] file ... 
DESCRIPTION 


ci Stores new revisionsinto RCS files. Each pathname matching an RCS suffix is taken to bean RCS file All others are 
assumed to be working files containing new revisions. ci deposits the contents of each working fileinto the corresponding 
RCS file If only a working fileis given, ci tries to find the corresponding RCS filein an RCS subdirectory and then in the 
working file’s directory. (For more details, see “File N aming,” later in this manual page.) 


For ci to work, the caller’s login must be on the access list, unless the access list is empty or the caller is the superuser or the 
owner of the file To append a new revision to an existing branch, the tip revision on that branch must be locked by the 
caller. O therwise, only anew branch can be created. This restriction is not enforced for the owne of the file if non-strict 
locking is used; see res(1). A lock hdd by someone dse can be broken with the rcs command. 


Unless the -+ option is given, ci checks whether the revision to be deposited differs from the preceding one If not, instead of 
creating a new revision ci reverts to the preceding one. To revert, ordinary ci removes the working file and any lock; ci -| 
keeps and ci -u removes any lock, and then they both generate a new working file much asif co -1 or co -u had been applied 
to the preceding revision. When reverting, any -n and -s options apply to the preceding revision. 


For each revision deposited, ci prompts for alog message. T he log message should summarize the change and must be 
terminated by end-of-file or by aline containing . by itself. If several files are checked in, ci asks whether to reuse the 
previous log message. | f the standard input is not aterminal, ci suppresses the prompt and uses the same log message for all 
files. (See also -m.) 


If theRCS file does not exist, ci creates it and deposits the contents of the working file as the initial revision (default 
number: 1.1). T he access list isinitialized to empty. Instead of the log message, ci requests descriptive text (See -t.) 


The number rev of the deposited revision can be given by any of the options -f, -i, -1, -j, -k, -1, -M, -q, -r, Or -u. rev can be 
symbolic, numeric, or mixed. Symbolic namesin rev must already be defined; see the -n and -n options for assigning names 
during checkin. If rev iS $, ci determines the revision number from keyword values in the working file 


If rev begins with a period, then the default branch (normally the trunk) is prepended to it. If rev isa branch number 
followed by a period, then the latest revision on that branch is used. 


If rev isarevison numbe,, it must be higher than the latest one on the branch to which rev belongs, or must start a new 
branch. 


If rev isa branch rather than a revision number, the new revision is appended to that branch. The level number is obtained 
by incrementing the tip revision number of that branch. If rev indicates a nonexistent branch, that branch is created with the 
initial revision numbered rev.1. 


If rev isomitted, ci tries to derive the new revision number from the caller’s last lock. If the caller has locked the tip revision 
of a branch, the new revision is appended to that branch. The new revision number is obtained by incrementing the tip 
revision number. If the caller locked anontip revision, anew branch is started at that revision by incrementing the highest 
branch number at that revision. T he default initial branch and levd numbers are 1. 


If rev isomitted and the caller has no lock, but owns the file and locking is not set to strict, then the revision is appended to 
the default branch. (N ormally the trunk; see the -b option of rcs(1).) 


Exception: On thetrunk, revisions can be appended to the end, but not inserted. 


° 


OPTIONS 
-rrev Check in revision rev. 
-r The bare -r option (without any revision) has an unusual meaningin ci. With other RCS 


commands, a bare -r option specifies the most recent revision on the default branch, but with ci, a 
bare -r option reestablishes the default behavior of releasing a lock and removing the working file, 
and is used to override any default -1 or -u options established by shal aliases or scripts. 

-l[rev] Works like -r, except it performs an additional co -1 for the deposited revision. T hus, the 
deposited revision is immediately checked out again and locked. T his is useful for saving a revision 
although one wants to continue editing it after the checkin. 

-u[rev] W orks like -1, except that the deposited revision is not locked. T his lets one read the working file 
immediately after checkin. 


The -1, bare -r, and -u options are mutually exclusive and silently override each other. For example, ci -u -r isequivalent 
to ci -r because bare -r overrides -u. 


-f[rev] Forces a deposit; the new revision is deposited even it is not different from the preceding one. 

-k[rev] Searches the working file for keyword values to determine its revision number, creation date, state 
and author— see co(1)— and assigns these values to the deposited revision, rather than computing 
them locally. It also generates a default login message noting the login of the caller and the actual 
checkin date. T his option is useful for software distribution. A revision that is sent to several sites 
should be checked in with the -k option at these sites to preserve the original number, date, author, 
and state. The extracted keyword values and the default log message can be overridden with the 
options -d, -m, -s, -w, and any option that carries a revision number. 


-q[rev] Quiet mode; diagnostic output is not printed. A revision that is not different from the preceding 
oneis not deposited, unless -f is given. 

-ifrev] Initial checkin; report an error if the RCS file already exists. This avoids race conditions in certain 
applications. 

-j[rev] Just check in and do not initialize; report an error if the RCS file does not already exist. 

-I[rev] Interactive mode the user is prompted and questioned even if the standard input is not a terminal. 

-d[date] Uses date for the checkin date and time. The date is specified in free format as explained in co(1). 


This is useful for lying about the checkin date, and for -k if no date is available If date is empty, 
the working file's time of last modification is used. 

-M[rev ] Se the modification time on any new working file to be the date of the retrieved revision. For 
example, ci -d -m -u f doesnot alter t’s modification time, even if t's contents change due to 
keyword substitution. U sethis option with care it can confuse make(1). 

mms g Uses the string msg as thelog message for all revisions checked in. By convention, log messages that 
start with # are comments and are ignored by programs like GN U emacs’s ve package Also, log 
messages that start with clumpname (followed by whitespace) are meant to be clumped together if 
possible, even if they are associated with different files; the clumpname label is used only for 
clumping, and is not considered to be part of the log message itself. 


-nname Assigns the symbolic name to the number of the checked-in revision. ci prints an error message if 
that name is already assigned to another number. 

-Nname Same as -n, except that it overrides a previous assignment of name. 

-sstate Sets the state of the checked-in revision to the identifier state. T he default state is exp. 

-tfile W rites descriptive text from the contents of the named file into the RCS file deleting the existing 
text. The file cannot begin with -. 

-t-string W rite descriptive text from thestring into theRCS file deleting the existing text. 


The -t option, in both its forms, has effect only during an initial checkin; it is silently ignored otherwise 


During the initial checkin, if -t isnot given, ci obtains the text from standard input, terminated by end-of-file or by a line 
containing a dot (.) by itself. T he user is prompted for the text if interaction is possible see -1. 
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For backwards compatibility with older versions of RCS, a bare -t option is ignored. 


-T 


-wl ogin 
-V 


-Vn 


-xsuffixes 


-zz0ne 


FILE NAMING 


Sé& the RCS file’s modification time to the new revision’s time if the former precedes the latter and 
there isa new revision; preserve the RCS file's modification time otherwise If you have locked a 
revision, ci usually updates the RCS file's modification time to the current time, because the lock is 
stored in the RCS file and removing the lock requires changing the RCS file. T his can create an 
RCS file newer than the working filein one of two ways: first, ci -m can create a working file with 
a date before the current time, second, when reveting to the previous revision the RCS file can 
change while the working file remains unchanged. These two cases can cause excessive 
recompilation caused by amake(1) dependency of the working fileon the RCS file The -t option 
inhibits this recompilation by lying about the RCS file's date. U se this option with care it can 
suppress recompilation even when a checkin of one working file should affect another working file 
associated with thesameRCS file. For example suppose theRCS file's time is 01:00, the (changed) 
working file’s time is 02:00, some other copy of the working file has a time of 03:00, and the 
current timeis 04:00. Then ci -d-T setstheRCS file's time to 02:00 instead of the usual 04:00; 
this causes make(1) to think (incorrectly) that the other copy isnewer than theRCS file 

Uses login for the author field of the deposited revision. U seful for lying about the author, and for 
-k if no author is available 

Print RCS's version numbe.. 

Emulate RCS version n. See co(1) for details. 

Specifies the suffixes for RCS files. A nonempty suffix matches any pathname ending in the suffix. 
An empty suffix matches any pathname of the form rcs/path or path1/RCS/path2. The -x option 
can specify a list of suffixes separated by /. For example -x,v/ specifies two suffixes: ,v and the 
empty suffix. If two or more suffixes are specified, they are tried in order when looking for an RCS 
file, the first onethat works is used for that file. If no RCS fileis found but an RCS file can be 
created, the suffixes are tried in order to determinethe new RCS file’s name T he default for 
suffixes is installation-dependent; normally it is ,v/ for hosts like UN 1X that permit commasin 
filenames, and is empty (that is, just the enpty suffix) for other hosts. 
Specifies the date output format in keyword substitution, and specifies the default time zone for 
date in the -ddate option. The zone should be enpty, anumeric UTC offset, or the special string 
LT for local time The default isan enpty zone, which uses the traditional RCS format of UTC 
without any time-zone indication and with slashes separating the parts of the date otherwise, times 
are output in ISO 8601 format with time zone indication. For example, if local timeis) anuary 11, 
1990, 8 p.m. Pacific Standard Time, aght hours west of UTC, then the time is output as follows: 








Option Time Output 

-2 1990/01/12 04:00:00 (default) 
-2LT 1990-01-11 20:00:00-08 
-2+05:30 1990-01-12 09:30:00+05:30 


The -z option does not affect dates stored in RCS files, which are always UTC. 


Pairs of RCS files and working files can be specified in three ways. (See also “Examples,” next.) 


1. Both theRCS file and the working file are given. The RCS pathname is of the form path1/workfilex and the working 
pathname is of the form path2/workfile where path1/ and path2/ are (possibly different or empty) paths, workfile isa 
filevame, and x isan RCS suffix. If x is empty, path1/ must start with rcs/ or must contain /Rcs/. 

2. Only theRCS fileis given. Then theworking file is created in the current directory and its name is derived from the 
name of the RCS file by removing path1/ and the suffix x. 


eee 


3. Only the working file is given. Then ci considers each RCS suffix X in turn, looking for an RCS file of the form path2/ 
RCS/workfilex or (if the former is not found and x isnonenpty) path2/workfilex. 


If the RCS file is specified without a path in one of the first two preceding scenarios, ci looks for the RCS file first in the 
directory ./rcs and then in thecurrent directory. 


ci reports an error if an attenpt to open an RCS file fails for an unusual reason, even if the RCS file’s pathname is just one 
of several possibilities. For example, to suppress use of RCS commands in a directory a, create a regular file named d/rcs so 
that casual attempts to use RCS commands in a fail because a/rcs is not a directory. 


EXAMPLES 


Suppose ,v isan RCS suffix and the current directory contains a subdirectory RCS with an RCS file io.c,v. Then each of 
the following commands checks in a copy of io.c into rcS/io.c,v as the latest revision, removing io.c: 

ci io.c; ci RCS/io.c,v; ci io.c,v; 

ci io.c RCS/io.c,v; ci io.c io.c,v; 

ci RCS/io.c,v io.c; ci io.c,v io.c; 


Suppose instead that the enpty suffix isan RCS suffix and the current directory contains a subdirectory RCS with an RCS 
file io.c. Then each of the following commands checks in a new revision: 

ci io.c; ci RCS/io.c; 

ci io.c RCS/io.c; 

ci RCS/io.c io.c; 


FILE MODES 


An RCS file created by ci inherits the read and execute permissions from the working file If the RCS file exists already, ci 
preserves its read and execute permissions. ci always turns off all write permissions of RCS files. 


FILES 


Temporary files are created in the directory containing the working file, and also in the temporary directory. (See TMPDIR 
under “Environment.”) A semaphore file or files are created in the directory containing the RCS file With anonempty 
suffix, the semaphore names begin with the first character of the suffix; therefore, do not specify an suffix whose first 
character could be that of a working fileaame With an empty suffix, the semaphore names end with an underscore (_), so 
working filenames should not end in _. ci never changesan RCS or working file N ormally, ci unlinks the file and creates a 
new one; but instead of breaking a chain of one or more symbolic links to an RCS file, it unlinks the destination file instead. 
Therefore ci breaks any hard or symbolic links to any working file it changes, and hard links to RCS files are ineffective, but 
symbolic links to RCS files are preserved. 


The effective user must be able to search and write the directory containing the RCS file N ormally, the real user must be 
able to read the RCS and working files and to search and write the directory containing the working file. however, some 
older hosts cannot easily switch between real and effective users, so on these hosts the effective user is used for all accesses. 
T he effective user is the same as the real user unless your copies of ci and co have setuid privileges. T hese privileges yidd 
extra security if the effective user owns all RCS files and directories, and if only the effective user can write RCS directories. 





Userscan control access to RCS files by setting the permissions of the directory containing the files, only users with write 
access to the directory can use RCS commandsto change its RCS files. For example, in hosts that allow a user to bdong to 
several groups, one can makea group’s RCS directories writable to that group only. T his approach suffices for informal 
projects, but it means that any group member can arbitrarily change the group’s RCS files, and can even renovethen 
entirely. H ence, more formal projects sometimes distinguish between an RCS administrator, who can change the RCS files 
at will, and other project members, who can check in new revisions but cannot otherwise change theRCS files. 


Setuid USE 


To prevent anybody but their RCS administrator from deleting revisions, a set of userscan enploy setuid privileges as 
follows: 
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m Check that the host supports RCS setuid use. Consult a trustworthy expert if there are any doubts. It is best if the 
setuid system calls works as described in POSIX 1003.1aD raft 5, because RCS can switch back and forth easily 
between real and effective users, even if the real user is root. If not, the second best isif the setuid system call supports 
saved setuid (the {_PoSIX_SAVED_1DS} behavior of POSIX 1003.1-1990); this fails only if the real or effective user is root. 
If RCS detects any failure in setuia, it quits immediately. 

m Chooseauser A to save asRCS administrator for the set of users. Only A can invoke the rcs command on the users 
RCS files. A should not be root or any other user with special powers. M utually suspicious sets of users should use 
different administrators. 

m ChooseapathnameB to bea directory of files to be executed by the users. 

m HaveA s& up B to contain copies of ci and co that are setuid to A by copying the commands from ther standard 
installation directory D as follows: 
mkdir B cp D/c[io] B chmod go-w,u+s B/c[io] 

m Have each user prepend B to his/her path as follows: 

PATH=B:$PATH; export PATH # ordinary shell 
set path=(B $path) # C shell 

m HaveA create each RCS directory R with write access only to A as follows: 
mkdir R chmod go-w R 

m If you want to let only certain users read the RCS files, put the users into a group G, and haveA further protect theRCS 
directory as follows: 
chgrp G Rchmod g-w,o-rwx R 

m HaveA copy old RCS files (if any) into R, to ensure that A owns them. 

m AnRCS file's access list limits who can check in and lock revisions. T he default access list is anpty, which grants 
checkin access to anyone who can read the RCS file If you want limit checkin access, have A invoke rcs -a on the file 
see res(1). In particular, res -e -aa limits access to just A. 

m HaveA initialize any new RCS files with res -i before initial checkin, adding the-a option if you want to limit checkin 
ACCESS. 

m@ Give setuid privileges only to ci, co, and resclean; do not give them to rcs or to any other command. 

m Donot useother setuid commands to invoke RCS commands; setuid is trickier than you think! 

ENVIRONMENT 

RCSINIT O ptions prepended to the argument list, separated by spaces. A backslash escapes spaces within an option. 
Thercsinit options are prepended to the argument lists of most RCS commands. Useful rcsin1T options 
include -q, -v, -x, and -z. 

TMPDIR N ame of the tanporary directory. If not set, the environment variables tue and TemPso are inspected 
instead and the first value found is taken; if none of them are set, a host-dependent default is used, 
typically /tmp. 

DIAGNOSTICS 


For each revision, ci prints the RCS file, the working file, and the number of both the deposited and the preceding revision. 
The exit status is zero if and only if all operations were successful. 
IDENTIFICATION 
Author: Walter F. Tichy. 
M anual page revision: 5.17; Release date 16 June 1995 
Copyright © 1982, 1988, 1989 Walter F. T ichy 
Copyright © 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert 


cidentd 
SEE ALSO 


co(1), emacs(1), ident(1), make(1), res(1), resclean(1), resdift(1), resintro(1), resmerge(1), rlog(1), setuid(2), resfile(5) 
Walter F. Tichy, “RCS—A System for Version Control,” Software Practice & Experience 15, 7 (July 1985), 637-654. 
GNU, 16 June1995 


cidentd 


cidentd— identd SYVer 


SYNOPSIS 


cidentd [-usqvnah] [-f file] [-1l file] [-t seconds] 


DESCRIPTION 


cidentd gives authentication information. 


cidentd isan RFC 1314- and 931-compliant identa daemon. It accepts connections on a port (113 default) and answers 
queries for port owner of a connection. command; 


cidentd normally terminates when the remote command does. T he options are as follows: 


-u Turns on the use of the . authiie filein the user's home directory to give the requesting systen whatever 
information the user provides. This file is overridden by the -a option and the system file the format is as 
follows: 

mynameis name -to-be-given # give this userid 
hideme # hide user id 
host -ip name -to-be-given # userid for them 
host-ip no-info # hide you to them 


host-ip can bea ip in dot notation or aname. The file is set so that whatever comes last is what they get. 


-s Closes the connection after a single query. 

-q Quits thedaemon after 1 connection (default in 1.0b). 

-v Turns on verbose logging to the syslogs. 

-n M akes cident act like the old school identd with nothing special. 

-a Enables the /etc/cident.users file for options, which overrides the user files if -u is specified. The format 

is as follows: 

username name -to-send # send this for username 
username # must send there username 
all name -to-send # send for every query 
all no-info # send nothing every query 
host-ip name -to-send # send to that host 
host-ip no-info # send nothing to them 


host-ip can bea ip in dot notation or aname. The file is set so that whatever comes last is what they get. 


-h Displays the help list to the screen you might not want to do this from some terminal types. 

-f Sets the file to find the ports and ids of connections. U se this to specify a file other than /proc/net/tcp. 

-1 U sed to specify afile other than /etc/cident.users must be used with the -a option unless you like 
redundancy. 


-t Sets the time out of a connection in seconds. T his does not work in this version to cidentd. 
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If no arguments are specified, the program just runs as normal, almost like the -n. 
cidentd -t 30 -a sets timer to 30 seconds and tellsit to look at .authlie files. 


FILES 


/etc/cidentd.users 
$(HOME) /.authlie 


SEE ALSO 


identd(1) 


BUGS 


N one that | know of. 


Linux/FreeBSD , M ay 1996 


cksum 

cksum— Checksum and count the bytes in afile 
SYNOPSIS 

cksum [—help] [—version] [file...] 
DESCRIPTION 


This manual page documents the GN U version of cksum. cksum Computes a cyclic redundancy check (CRC) for each named 
file, or the standard input if none are given or when afile named - is given. It printsthe CRC for each file along with the 
number of bytesin the file, and the filename unless no arguments were given. 


cksum iS typically used to make sure that files transferred by unreliable means (such as netnews) have not been corrupted. T his 
is accomplished by comparing the cksum output for the received files with the cksum output for the original files. The CRC 


algorithm is specified by the PO SIX.2 standard. It is not compatible with the BSD or System V sum programs; it is more 
robust. 


Available options are 
—help Print a usage message and exit with anonzero status. 
—version Print version information on standard output then exit. 


GNU Tet Utilitie 


clear 


clear— C lear terminal screen 


SYNOPSIS 
clear 
DESCRIPTION 


clear Calls tput(1) with the clear argument. T his causes tput to attempt to clear the screen, checking the data in /etc/termcap 
(for the GNU or BSD tput) or in the terminfo database (for thencurses tput) and sending the appropriate sequence to the 
terminal. T hiscommand can be redirected to clear the screen of some other terminal. 


iz 


SEE ALSO 


reset(1), stty(1), tput(1) 


AUTHOR 


Rik Faith (faith@cs.unc. edu) 
Linux 0.99, 10 October 1993 


cmuwmtopbm 

cmuwmtopbm— Convert aCMU window manager bitmap into a portable bitmap 
SYNOPSIS 

cmuwmtopbm [cmuwmfile] 
DESCRIPTION 

Reads aCMU window manager bitmap as input. Produces a portable bitmap as output. 
SEE ALSO 

pbmtocmuwm(1), pbm(5) 
AUTHOR 

Copyright © 1989 by J ef Poskanzer 

15 April 1989 

CO 

co— Check out RCS revisions 
SYNOPSIS 

co [options] file ... 
DESCRIPTION 


co retrieves a revision from each RCS file and stores it into the corresponding working file 
Pathnames matching an RCS suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(1). 


Revisions of an RCS filecan be checked out locked or unlocked. Locking a revision prevents overlapping updates. A revision 
checked out for reading or processing (for example, compiling) need not be locked. A revision checked out for editing and 
later checkin must normally be locked. C heckout with locking fails if the revision to be checked out is currently locked by 
another user. (A lock can be broken with rcs(1).) Checkout with locking also requires the caller to be on the access list of the 
RCS file, unless he is the owne’ of the file or the superuser, or the access list is enpty. Checkout without locking is not 
subject to access list restrictions, and is not affected by the presence of locks. 


A revision is sdected by options for revision or branch numbe,, checkin date/time, author, or state. W hen thesdection 
options are applied in combination, co retrieves the latest revision that satisfies all of then. If none of the sdection optionsis 
specified, co retrieves the latest revision on the default branch, normally the trunk; see the -b option of res(1). A revision or 
branch number can be attached to any of the options -f, -1, -1, -M, -p, -q, -r, or -u. The options -d (date), -s (state), and -w 
(author) retrieve from asingle branch, the selected branch (which is specified by -+ or -u), or the default branch. 


A co command applied to an RCS file with no revisions creates a zero-length working file. co always performs keyword 
substitution. 


OPTIONS 


-r[rev] 


-l[rev] 


-u[rev] 


-f[rev] 


-kkv 


-kkvl 
-kk 


-ko 
-kb 


-kv 


-plrev] 


-q[rev] 
-I[rev] 
-ddate 
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Retrieves the latest revision whose number is less than or equal to rev. If rev indicates a branch 
rather than arevision, the latest revision on that branch is retrieved. If rev is omitted, the latest 
revision on the default branch is retrieved; see the -b option of rcs(1). If rev iS $, co determines the 
revision number from keyword values in the working file. O therwise a revision is composed of one 
or more numeric or symbolic fidds separated by periods. Ifrev begins with a period, then the 
default branch (normally the trunk) is prepended to it. Ifrev isa branch number followed by a 
period, then the latest revision on that branch is used. The numeric equivalent of a symbolic field is 
specified with the -n option of the commands ci(1) and res(1). 

Same as -r, except that it also locks the retrieved revision for the caller. 

Same as -r, except that it unlocks the retrieved revision if it was locked by the caller. If rev is 
omitted, -u retrieves the revision locked by the caller, if there isone otherwise, it retrieves the latest 
revision on the default branch. 

Forces the overwriting of the working file, useful in connection with -q. (See also “File M odes,” 
later in this manual page.) 

Generate keyword strings using the default form, for example, $Revision: 5.13 $ forthe Revision 
keyword. A locker’s nameis inserted in the value of the Header, Id, and Locker keyword strings only 
as a file is being locked, that is, by ci -1 andco -1. Thisis the default. 

Like -kkv, except that a locker’s name is always inserted if the given revision is currently locked. 
Generate only keyword names in keyword strings; omit their values. (See “K eyword Substitution,” 
later in this manual page.) For example, for the revision keyword, generate the string $Revision$ 
instead of $Revision: 5.13 $. T his option is useful to ignore differences due to keyword substitu- 
tion when comparing different revisions of a file. Log messages are inserted after sLogs keywords 
even if -kk is specified, since this tends to be more useful when merging changes. 

Generate the old keyword string, present in the working file just before it was checked in. For 
example, for the Revision keyword, generate the string $Revision: 1.1 $ instead Of $Revision: 5.13 
$ if that is how the string appeared when the file was checked in. T his can be useful for file formats 
that cannot tolerate any changes to substrings that happen to take the form of keyword strings. 
Generate a binary image of the old keyword string. T his acts like -ko, except it performs all 
working file input and output in binary mode. T his makes little difference on PO SIX and UNIX 
hosts, but on D OS-like hosts one should use rcs -i -kb to initialize an RCS filenormally refuses 
to merge files when -kb isin effect. 

Generate only keyword values for keyword strings. For example for the Revision keyword, generate 
the string 5.13 instead of $Revision: 5.13 $. Thiscan hap generate files in programming languages 
where it is hard to strip keyword delimiters like $Revision: $ from astring. H owever, further 
keyword substitution cannot be performed once the keyword names are removed, so this option 
should be used with care. Because of this danger of losing keywords, this option cannot be 
combined with -1, and the owner write permission of the working file is turned off; to edit the file 
later, check it out again without -kv. 

Prints the retrieved revision on the standard output rather than storing it in the working file This 
option is useful when co is part of a pipe 

Quiet mode; diagnostics are not printed. 

Interactive mode the user is prompted and questioned even if the standard input is not a terminal. 
Retrieves the latest revision on the sdected branch whose checkin date/time is less than or equal to 
date. The date and time can be given in free format. The time zone -t stands for local time, other 
common time zone names are understood. For example, the following dates are equivalent if local 
time is January 11, 1990, 8 p.m. Pacific Standard Time, aight hours west of C oordinated U niversal 
Time (UTC): 


8:00 PM It 
4:00 AM, Jan. 12, 1990 D efault is UTC 





a EE 


1990-01-12 04:00:00+00 ISO 8601 (UTC) 
1990-01-11 20:00:00-08 ISO 8601 (local time) 
1990/01/12 04:00:00 Traditional RCS format 
Thu Jan 11 20:00:00 1990 LT Output of ctime(3) +LT 
Thu Jan 11 20:00:00 PST 1990 Output of date(1) 


Fri Jan 12 04:00:00 GMT 1990 
Thu, 11 Jan 1990 20:00:00 -0800 Internet RFC 822 
12-} anuary-1990, 04:00 WET 


M ost fields in the date and time can be defaulted. T he default time zone is normally UTC, but this can be overridden by the 
-z option. T heother defaults are determined in the order year, month, day, hour, minute, and second (most to least 
significant). At least one of these fields must be provided. For omitted fidds that are of higher significance than the highest 
provided field, the timezone's current values are assumed. For all other omitted fidds, the lowest possible values are 
assumed. For example without -z, thedate 20, 10:30 defaults to 10:30:00 UTC of the 20th of the UTC time zone’s current 
month and year. The date/time must be quoted if it contains spaces. 


-M[rev ] 


-sstate 
-T 


-w[login] 


-jjoinlist 


-Vn 


Sets the modification time on the new working file to be the date of the retrieved revision. Use this 
option with care it can confuse make(1). 

Retrieves the latest revision on the sdected branch whose state is set to state. 

Preserves the modification time on the RCS file even if the RCS file changes because a lock is 
added or renoved. This option can suppress extensive recompilation caused by amake(1) depen- 
dency of some other copy of the working file on the RCS file. Use this option with care; it can 
suppress recompilation even when it is needed, in other words, when the change of lock would 
mean a change to keyword strings in the other working file 

Retrieves the latest revision on the selected branch that was checked in by the user with login name 
login. If the argument | ogin is omitted, the caller’s login is assumed. 

Generates a new revision which is the join of the revisions on j oi nl ist. This option is largely made 
obsolete by resmerge(1), but is retained for backwards compatibility. 

Thejoinlist isacomma-separated list of pairs of the formrev2:rev3, whererev2 andrev3 are 
(symbolic or numeric) revision numbers. For the initial such pair, rev1 denotes the revision selected 
by the options -f, -w. For all other pairs, rev1 denotes the revision generated by the previous pair. 
(Thus, the output of one join becomes the input to the next.) 

For each pair, co joinsrevisionsrev1 and rev3 with respect to rev2. T his means that all changes that 
transform rev2 into rev1 are applied to acopy of rev3. Thisis particularly useful ifrev1 and rev3 
are the ends of two branches that haver ev2 asa common ancestor. If revi<rev2<rev3 on thesame 
branch, joining generates a new revision which islikerev3, but with all changes that lead fromrev1 
torev2 undone If changesfromrev2 torev1 overlap with changes from rev2 to rev3, co reports 
overlaps as described in merge(1). 

For the initial pair, rev2 can be omitted. The default is the common ancestor. If any of the 
arguments indicate branches, the latest revisions on those branches are assumed. T he options -1 
and -u lock or unlock revi. 

Prints RCS’s version number. 

Emulates RCS version n, wheren can be3, 4, or 5. This can be useful when interchanging RCS 
files with others who are running older versions of RCS. To see which version of RCS your 
correspondents are running, have them invoke res -v; this works with newer versions of RCS. If it 
doesn’t work, have them invoke rlog on an RCS file; if none of the first few lines of output contain 
the string branch:, it is version 3; if the dates’ years have just two digits, it is version 4; otherwise, it 
isversion 5. An RCS file generated while emulating version 3 losesits default branch. An RCS 
revision generated while enulating version 4 or earlier has a timestamp that is off by up to 13 
hours. A revision extracted while emulating version 4 or earlier contains abbreviated dates of the 
form yy/mm/dd and can also contain different whitespace and line prefixes in the substitution for 
$Log$. 
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-xsuf fixes U ses suffixes to characterize RCS files. See ci(1) for details. 

-zz0ne Specifies the date output format in keyword substitution, and specifies the default time zonefor 
date in the -ddate option. Thezone should beempty, anumeric UTC offset, or the special string 
LT for local time The default isan empty zone, which uses the traditional RCS format of UTC 
without any time zone indication and with slashes separating the parts of the date otherwise times 
are output in ISO 8601 format with time zone indication. For example, if local timeis) anuary 11, 
1990, 8 p.m. Pacific Standard Time, aght hours west of UTC, then the time is output as follows: 





Option Time Output 

-Z 1990/01/12 04:00:00 (default) 
-ZLT 1990-01-11 20:00:00-08 
-2+05:30 1990-01-12 09:30:00+05:30 


The -z option does not affect dates stored in RCS files, which are always UTC. 
KEYWORD SUBSTITUTION 


Strings of the form $ keyword $aNd$ keyword : ... $ embedded in the text are replaced with strings of theform $ keyword 
: value $,Wherekeyword and value are pairsin the following list. Keywords can be embedded in literal strings or comments 
to identify a revision. 


Initially, the user enters strings of the form $key words. On checkout, co replaces these strings with strings of theform 

$keyword : value$. If a revision containing strings of the latter form is checked back in, the val ue fields will be replaced 
during the next checkout. T hus, the keyword values are automatically updated on checkout. T his automatic substitution can 
be modified by the -k options. 


K eywords and their corresponding values: 





$Aut hor Thelogin name of the user who checked in the revision. 

Dates The date and time the revision was checked in. With -zzone, anumeric time zone offset is 
appended; otherwise the dateisUTC. 

Header $ A standard header containing the full pathname of the RCS file the revision number, the date and 


time, the author, the state, and the locker (if locked). With -zzone, anumeric time zone offset is 
appended to the date; otherwise, thedateisUTC. 





1d$ Same as $Header $, except that the RCS filename is without a path. 
Locker $ The login name of the user who locked the revision (empty if not locked). 
Logs The log message supplied during checkin, preceded by a header containing the RCS filename the 


revision number, the author, and the date and time W ith -zzone anumeric time zone offset is 
appended; otherwise the date is UTC. Existing log messages are not replaced. Instead, thenew log 
message is inserted after slog: ... $. Thisis useful for accumulating a complete changelogin a 
source file. 


Each inserted line is prefixed by the string that prefixes the $Log$ line For example, if the $og$ lineis // $Log: tan.cc $, 
RCS prefixes each line of the log with //. Thisis useful for languages with comments that go to the end of the line The 
convention for other languages is to use a * prefix inside a multiline comment. For example, the initial log comment of aC 
program conventionally is of the following form: 

/* 
* $Log$ 
*/ 
For backwards compatibility with older versions of RCS, if the log prefix is /* or (* surrounded by optional whitespace, 
inserted log lines contain a space instead of / or (; however, this usage is obsolescent and should not be relied on. 


$Name$ The symbolic name used to check out the revision, if any. For example co -r Joe generates $name : 
Joe $. Plain co generates just $Name: $. 


se 


SRCSfiles Thename of theRCS file without a path. 

$Revision$ Therevision number assigned to the revision. 

$Sources The full pathname of the RCS file 

$States The state assigned to the revision with the -s option of rcs(1) or ci(1). 


The following characters in keyword values are represented by escape sequences to keep keyword strings well-formed. 





Character Escape Sequence 
tab \t 

newline \n 

space \040 

$ \044 

\ \\ 

FILE MODES 


The working file inherits the read and execute permissions from theRCS file In addition, theowner write permission is 
turned on, unless -kv is set or the file is checked out unlocked and locking is set to strict; see rcs(1). 


If a file with the name of the working file exists already and has write permission, co aborts the checkout, asking beforehand 
if possible. If the existing working file is not writable or -¢ isgiven, the working file is deleted without asking. 

FILES 
co accesses files much as ci(1) does, except that it does not need to read the working file unless a revision number of $ is 
specified. 

ENVIRONMENT 


RCSINIT O ptions prepended to the argument list, separated by spaces. See ci(1) for details. 


DIAGNOSTICS 
TheRCS pathname, the working pathname, and the revision number retrieved are written to the diagnostic output. T he exit 
status is zero if and only if all operations were successful. 


IDENTIFICATION 
Author: Walter F. Tichy. 
M anual Page Revision: 5.13; Release D ate: 1995/06/01. 
Copyright © 1982, 1988, 1989 Walter F. Tichy. 
Copyright © 1990, 1991, 1992, 1993, 1994, 1995 Paul Egget. 


SEE ALSO 
resintro(1), ci(1), ctime(3), date(1), ident(1), make(1), res(1), resclean(1), resdift(1), rc-smerge(1), rlog(1), restile(5) 
Walter F. Tichy, “RCS—A System for Version Control,” Software Practice & Experience 15, 7 (July 1985), 637-654. 


LIMITS 
Links to the RCS and working files are not preserved. 


There is no way to selectivey suppress the expansion of keywords, except by writing them differently. In nroff and troff, 
thisis done by enbedding the null-character \a into the keyword. 


GNU, 1June1995 
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col 


col— Filter reverse line feeds from input 


SYNOPSIS 


col [-bfx] [-1 num] 


DESCRIPTION 


col filters out reverse (and half-reverse) line feeds so the output isin the correct order with only forward and half-forward 
line feeds, and replaces whitespace characters with tabs where possible. This can be useful in processing the output of 
nroff(1) and tb1(1). col reads from standard input and writes to standard output. 


The options are as follows: 


-b Do not output any backspaces, printing only the last character written to each column position. 

-f Forward half-line feeds are permitted (fine mode). N ormally characters printed on a half-line boundary 
are printed on the following line 

“x Output multiple spaces instead of tabs. 

-lnum Buffer at least num lines in memory. By default, 128 lines are buffered. 


The control sequences for carriage motion that col understands and ther decimal values are listed in the following table 


Control Sequence 


Dedmal Value 





Esct+/ 
Esc+8 
Esc+9 
Backspace 
Carriage return 
N ewline 
Shift in 
Shift out 
Space 

Tab 
Vertical tab 


Reverse line feed (escape then 7) 

H alf-reverse line feed (escape then 8) 

H alf-forward line feed (escape then 9) 

M oves back one column (8); ignored in the first column 
(13) 

Forward line feed (10); also does carriage return 
Shift to normal character set (15) 

Shift to alternate character set (14) 

M oves forward one column (32) 

M oves forward to next tab stop (9) 

Reverse line feed (11) 


All unrecognized control characters and escape sequences are discarded. 


col Keeps track of the character set as characters are read and makes sure the character set is correct when they are output. 


If the input attempts to back up to the last flushed line, coi will display a warning message. 


SEE ALSO 


expand(1), nrof#(1), tb1(1) 


HISTORY 


A col command appeared in version 6 AT&T UNIX. 


17 June1991 


colrm 


colcrt 


colert— Filter nroff output for CRT previewing 


SYNOPSIS 


colert [-] [-2] [file ...] 


DESCRIPTION 


colert provides virtual half-line and reverse line feed sequences for taminals without such capability, and on which 
overstriking is destructive. H alf-line characters and underlining (changed to dashing -) are placed on new lines in between 
the normal output lines. 


Available options: 


- Suppress all underlining. T his option is especially useful for previewing all boxed tables from tb1(1). 

-2 Causes all half-lines to be printed, effectively double spacing the output. N ormally, a minimal space 
output format is used which will suppress empty lines. The program never suppresses two consecutive 
empty lines, however. The -2 option is useful for sending output to theline printer when the output 
contains superscripts and subscripts that would otherwise be invisible 


EXAMPLES 

A typical use of colcrt would be 

tbl exum2.n | nroff -ms | colcrt - | more 
SEE ALSO 

nroff(1), troft(1), co1(1), more(1), u1(1) 
BUGS 


Should fold underlines onto blanks even with the - option so that a true underline character would show. 
Can't back up morethan 102 lines. 


General overstriking is lost; as a special case ! overstruck with '' or underline becomes +. Lines are trimmed to 132 
characters. 


Some provision should be made for processing superscripts and subscriptsin documents that are already double-spaced. 
HISTORY 
The colert command appeared in BSD 3.0. 
BSD 3, 30 June1993 


colrm 


colrm— Remove columnsfrom afile 


SYNOPSIS 


colrm [startcol [endcol ]] 


DESCRIPTION 
colrm removes sdected columns from a file. Input is taken from standard input. O utput is sent to standard output. 


If called with one parameter, the columns of each line will be renoved starting with the specified column. If called with two 
parameters, the columns from the first column to the last column will be removed. 


Column numbering starts with column 1. 


Part |: User Commands 


SEE ALSO 


awk(1), column(1), expand(1), paste(1) 
HISTORY 
The colrm command appeared in BSD 3.0. 
BSD 3, 14March 1991 


column 


column— C olumnate lists 


SYNOPSIS 


column [-tx] [-ccolumns] [-ssep] [...file] 


DESCRIPTION 


The column utility formats its input into multiple columns. Rows are filled before columns. Input istaken from file operands, 
or, by default, from the standard input. Empty lines are ignored. 


The options are as follows: 


-c Output is formatted for adisplay columns wide 

-s Specify a set of characters to be used to ddimit columns for the -t option. 

-t D eterminethe number of columns the input contains and create a table. Columns are ddimited with 
whitespace, by default, or with the characters supplied using the -s option. Useful for pretty-printing 
displays. 

“x Fill columns before filling rows. 


Column exits @ on success, >o if an error occurred. 


ENVIRONMENT 


The environment variable coumns is used to determine the size of the screen if no other information is available. 


EXAMPLES 


(printf "PERM LINKS OWNER SIZE MONTH DAY HH:MM/YEAR NAME"; ls -1 j sed 1d) j column -t 


SEE ALSO 
colrm(1), 1s(1), paste(1), sort(1) 


HISTORY 


The column command appeared in BSD 4.3 Reno. 
6 June1993 


comm 


comm— C ompare two sorted files line by line 


SYNOPSIS 


comm [-123] [—help] [—version] filel file2 


convdate 
DESCRIPTION 


This manual page documents the GN U version of comm. comm prints lines that are common, and lines that are unique, to two 
input files. The two files must be sorted before comm can be used. T he filename - means the standard input. 


With no options, comm produces three column output. Column one contains lines unique to fi! e1, column two contains 
lines unique to fil e2, and column three contains lines common to both files. 


OPTIONS 
The options -1, -2, and -3 suppress printing of the corresponding columns. 
—help Print a usage message and exit with anonzero status. 
—version Print version information on standard output then exit. 
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convdate— C onvert time/date strings and numbers 


SYNOPSIS 


convdate [ -c ][-n ][-s ] arg... 


DESCRIPTION 
convdate translates the date/time strings specified as arguments on its command line, outputting the results one to a line. 


If the -s flag isused, then each argument is taken as a date string to be parsed by parse -date(3) and is output asa string 
formatted by ctime(3). This is the default. 


If the -n flag is used, then each argument is converted the same way but is output as atime t; see time(2). 
If the -c flag is used, then each argument istaken to beatimet and is output in ctime format. 
H ere’s an example 





% convdate 'feb 10 10am' 
Sun Feb 10 10:00:00 1991 


% convdate 12pm 5/4/90 
Fri Dec 13 00:00:00 1991 
Fri May 4 00:00:00 1990 


% convdate -n ‘feb 10 1@am' ‘12pm 5/4/90' 
666198000 

641880000 

% convdate -c 666198000 

Sun Feb 10 10:00:00 1991 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net). 


SEE ALSO 


parsedate(3) 
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cp 


cp— Copy files 
SYNOPSIS 


cp [options] source dest 


cp [options] source... directory 


O ptions: 


[-abdfilprsuvxPR] [-S backup-suffix] [-V fnumbered,existing,simpleg] [—backup] 
[—no-dereference] [—force] [—interactive] [—one-file-system] [—preserve] 
[—recursive][—update] [—verbose] [—suffix=backup-suffix] 
[—version-control=fnumbered,existing,simpleg] [—archive] [—parents] [—link] 
[—symbolic-link] [—help] [—version] 


DESCRIPTION 


This manual page documents the GN U version of cp. If the last argument names an existing directory, cp copies each other 
given file into a file with the same name in that directory. O therwise if only two files are given, it copies the first onto the 
second. It is an error if the last argument is not a directory and more than two files are given. By default, it does not copy 


directories. 


OPTIONS 


-a, —archive 


-b, —backup 


-d, —no-dereference 


-f, —force 
-i, —interactive 
-1, —link 


-P, —parents 


-p, —preserve 


-s, —symbolic-link 


-u, —update 


-v, —verbose 

-x, —one-file-system 
-R, —recursive 
—help 

—version 


-S, —suffix backup-suffix 


Preserve as much as possible of the structure and attributes of the original filesin the copy. 
The same as -dpr. 


M ake backups of files that are about to be overwritten or removed. 


Copy symbolic links as symbolic links rather than copying the files that they point to, and 
preserve hard link relationships between source files in the copies. 


Remove existing destination files. 
Prompt whether to overwrite existing regular destination files. 
M ake hard links instead of copies of nondirectories. 


Form the name of each destination file by aopending to the target directory a slash and the 
specified name of the source file. The last argument given to cp must be the name of an 
existing directory. For example the command cp —parents a/b/c existing dir copies the 
file a/b/c to existing_dir/a/b/c, creating any missing intermediate directories. 


Preserve the original files’ owner, group, permissions, and timestamps. 
Copy directories recursiveay, copying all nondirectories as if they were regular files. 


M ake symbolic links instead of copies of nondirectories. All source filaaames must be 
absolute (starting with /) unless the destination files are in the current directory. This 
option produces an error message on systems that do not support symbolic links. 


Do not copy anondirectory that has an existing destination with thesame or newer 
modification time 


Print the name of each file before copying it. 

Skip subdirectories that are on different filesystems from the one that the copy started on. 
Copy directories recursively. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 


The suffix used for making simple backup files can be set with the SIMPLE_BACKUP_SUFFIX 
environment variable, which can be overridden by this option. If neither of thoseis given, 
the default is ~, asit isin emacs. 
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-V, —version-control The type of backups made can be set with the versIon_conTROL environment variable, which 

{numbered, existing, simple} can be overridden by this option. If verston_contro is not set and this option is not given, 
the default backup type is existing. T he value of the verston_conTROL environment variable 
and the argument to this option are like the GNU emacs version- control variable they 
also recognize synonyms that are more descriptive. The valid values are (unique abbrevia- 
tions are accepted) the following: 


t OF numbered Always make numbered backups 

nil OF existing M ake numbered backups of files that already have them, 
simple backups of the others 

never OF simple Always make simple backups 
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ccecp, cpp— The GNU C-compatible compiler preprocessor 


SYNOPSIS 


cccp -$][-A predicate [( value )]] [ -C ][-D name [ = definition ]] 
-dD][-dM][-I\ directory ][-H ][-I- ][-imacros file ][- 

include file ][-idirafter dir ][-iprefix prefix ][-iwithprefix dir ] 
-lang-c][-lang-c++][-lang-objc ][-lang-objc++ ][-lint ][- 

M[-MG ]] [ -MM[-MG ]] [ -MD file ][-MMD file ][-nostdinc ] 
-nostdinc++][-P][-pedantic ][-pedantic-errors ][-traditional ] 
-trigraphs ][-U name ][-undef ][-Wtrigraphs ][-Wcomment ] 

-Wall ][-Wtraditional ] 

infile j- ][ outfile j- ] 





DESCRIPTION 


TheC preprocessor isa macro processor that isused automatically by theC compiler to transform your program before 
actual compilation. It is called a macro processor because it allows you to define macros, which are brief abbreviations for 
longer constructs. 


TheC preprocessor provides four separate facilities that you can use as you see fit: 


m Inclusion of header files. T hese are files of declarations that can be substituted into your program. 

m Macro expansion. You can define macros, which are abbreviations for arbitrary fragments of C code, and then theC 
preprocessor will reolacethe macros with their definitions throughout the program. 

m Conditional compilation. U sing special preprocessing directives, you can include or exclude parts of the program 
according to various conditions. 

m@ Linecontrol. lf you use a program to combine or rearrange sourcefiles into an intermediate file which is then compiled, 
you can use line control to inform the compiler of where each source line originally came from. 


C preprocessors vary in some details. For a full explanation of the GNU C preprocessor, see the info file cpp. info, or the 
manual T heC Preprocessor . Both of these are built from the same documentation source file, cpp.texinfo. TheGNU C 
preprocessor provides a superset of the features of AN SI Standard C. 


AN SI Standard C requires the rection of many harmless constructs commonly used by today’s C programs. Such 
incompatibility would be inconvenient for users, so the GNU C preprocessor is configured to accept these constructs by 
default. Strictly speaking, to get AN SI Standard C, you must use the options -trigraphs, -undef, and -pedantic, but in 
practice the consequences of having strict AN SI Standard C make it undesirable to do this. 


When you use theC preprocessor, you will usually not have to invoke it explicitly: the C compiler will do so automatically. 
H owever, the preprocessor is sometimes useful individually. 


When you call the preprocessor individually, either name (cpp or cccp) will do; they are completely synonymous. 


Part |: User Commands 


TheC preprocessor expects two filenames as arguments, infile and outfile. The preprocessor reads infile together with 
any other files it specifies with #include. All the output generated by the combined input files is written in outfile. Either 
infile Or outfile may be -, which as infile means to read from standard input and as outfile means to write to standard 
output. Also, if outfile or both filenames are omitted, the standard output and standard input are used for the omitted 


filenames. 


OPTIONS 


H ereisa table of command options accepted by the C preprocessor. T hese options can also be given when compiling aC 
program; they are passed along automatically to the preprocessor when it is invoked by the compiler. 


-P 


-C 


-traditional 


-trigraphs 


-pedantic 


-pedantic-errors 
-Wtrigraphs 
-Wcomment 
-Wcomments 

-Wall 
-Wtraditional 

-I directory 


-nostdinc 


-nostdinct+ 


-D name 


-D name=definition 


Inhibit generation of # lines with linenumber information in the output from the preprocessor. 
This might be useful when running the preprocessor on something that isnot C code and will be 
sent to aprogram which might be confused by the# lines. 

Do not discard comments: pass them through to the output file Comments appearing in 
arguments of a macro call will be copied to the output before the expansion of the macro call. 

Try to imitate the behavior of old-fashioned C, as opposed to ANSI C. 

Process AN SI standard trigraph sequences. T hese are three-character sequences, all starting with 22, 
that are defined by AN SI C to stand for single characters. For example, 22/ stands for \, so 2?/n isa 
character constant for a newline. Strictly speaking, theGN U C preprocessor does not support all 
programsin AN SI Standard C unless -trigraphs is used, but if you ever notice the difference it 
will be with relief. You don’t want to know any more about trigraphs. 

Issue warnings required by theAN SI C standard in certain cases such as when text other than a 
comment follows #e1se or #endif. 

Like -pedantic, except that errors are produced rather than warnings. 

W arn if any trigraphs are encountered (assuming they are enabled). 

W arn whenever a comment-start sequence /* appears in acomment. (Both forms have the 

same effect.) 

Requests both -wtrigraphs and -Wcomment (but not -wtraditional). 

Warn about certain constructs that behave differently in traditional and ANSI C. 

Add the directory directory to theend of thelist of directories to be searched for header files. T his 
can be used to override a system header file, substituting your own version, since these directories 
are searched before the system header file directories. If you use more than one -1 option, the 
directories are scanned in left-to-right order; the standard system directories come after. 

Any directories specified with -1 options before the -1- option are searched only for the case of 
#include " file "; they arenot searched for #include < file >. 

If additional directories are specified with -1 options after the -1-, these directories are searched for 
all #include directives. 

In addition, the -1- option inhibits the use of the current directory as the first search directory for 
#include " file ". Therefore the current directory is searched only if it is requested explicitly with 
-1 followed by a period (.). Specifying both -1- and -1. allows you to control precisely which 
directories are searched before the current one and which are searched after. 

Do not search the standard system directories for header files. O nly the directories you have 
specified with -1 options (and the current directory, if appropriate) are searched. 

Do not search for header files in the C-++specific standard directories, but do still search the othe 
standard directories. (T his option is used when building 1ibg++.) 

Predefinename asamacro, with definition 1. 

Predefinenameas a macro, with definition definition. There areno restrictions on the contents of 
definition, but if you are invoking the preprocessor from a shdl or shell-like program, you may 
need to use the shell’s quoting syntax to protect characters such as spaces that have a meaning in 
the shell syntax. If you use more than one -p for the samename, the rightmost definition takes 
effect. 
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-U name Do not predefine name. If both -u and -p are specified for onename, the -u beats the -p and the 
nameis not predefined. 

-undef Do not predefine any nonstandard macros. 

-A name (value) Assert (in the same way as the #assert directive) the predicate name with tokenlist value. 


Remember to escape or quote the parentheses on shal command lines. You can use -A- to disable 
all predefined assertions; it also undefines all predefined macros. 

-dM Instead of outputting the result of preprocessing, output alist of #define directivesfor all the 
macros defined during the execution of the preprocessor, including predefined macros. T his gives 
you a way of finding out what is predefined in your version of the preprocessor; assuming you have 
no file foo.h, the command 
touch foo.h; cpp -dM foo.h 
will show the values of any predefined macros. 


-dD Like -am except in two respects: it does not include the predefined macros, and it outputs both the 
#define directives and the result of preprocessing. Both kinds of output go to the standard output 
file. 

-M[-MG] Instead of outputting the result of preprocessing, output a rule suitable for make describing the 


dependencies of the main source file T he preprocessor outputs one make rule containing the 
object filename for that source file, a colon, and the names of all the included files. If there are 
many included files then the rule is split into several lines using \\ (newline). 

-m@ Says to treat missing header files as generated files and assume they live in the same directory as 
the source file It must be specified in addition to -m. 

This feature is used in automatic updating of makefiles. 


-MM[-MG] Like -m but mention only thefiles included with #include " file ". System header files included 
with #include < file > are omitted. 
-MDF i | Like -u but the dependency information is written to file. Thisisin addition to compiling the file 


as specified. -mp does not inhibit ordinary compilation the way -m does. 

W hen invoking gcc, do not specify thefile argument. gcc will create filenames made by replacing 
.c with .d at the end of theinput filerames. 

In Mach, you can usetheutility ma to merge multiple files into a single dependency file suitable for 
using with the make command. 


-MMDE i |e Like -u except mention only user header files, not system header files. 
-H Print the name of each header file used, in addition to other normal activities. 
-imacros file Process file as input, discarding the resulting output, before processing the regular input file. 


Because the output generated from file is discarded, the only effect of -imacros file isto make the 
macros defined in file available for use in the main input. T he preprocessor evaluates any -p and -u 
options on the command line before processing -imacros file 
-include file Processtile asinput, and include all the resulting output, before processing the regular input file 
-idirafter dir Add the directory dir to the second include path. The directories on the second include path are 
searched when a header file is not found in any of the directoriesin the main include path (the one 
that -1 adds to). 


-iprefix prefix Specify prefix asthe prefix for subsequent -iwithprefix options. 

-iwithprefix dir Add adirectory to thesecond include path. The directory’s nameis made by concatenating prefix 
and dir, where prefix was specified previously with -iprefix. 

-lang-c Specify the source language. -1ang-c++ makes the preprocessor handle C ++ comment syntax, 

-lang-ct++ and includes extra default include directories for C , and -1ang-objc enables the O bjective C 

-lang-objc #import directive -1ang-c explicitly turns off both of these extensions, and -1ang-objc++ enables 

-lang-objc++ both. T hese options are generated by the compiler driver gcc, but not passed from the gcc 
command line 

-lint Look for commands to the program checker 1int embedded in comments, and emit then preceded 


by #pragma lint. For example the comment /* NOTREACHED */ becomes #pragma lint NOTREACHED. 
This option is available only when you call cpp directly; gcc will not pass it from its command line. 
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-$ Forbid the use of ¢ in identifiers. This is required for AN SI conformance gcc automatically 
supplies this option to the preprocessor if you specify -ansi, but gcc doesn’t recognize the -$ 
option itself; to use it without the other effects of -ansi, you must call the preprocessor directly. 

SEE ALSO 
cpp entry in info; TheC Preprocessor, Richard M. Stallman. 
gec(1); gcc entry in info; USng and PortingGNU CC (for version 2.0), Richard M. Stallman. 


COPYING 


Copyright © 1991, 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim 
copies of this manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


GNU Tools, 30 April 1993 
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crontab— M anipulate per-user crontabs (D illon’s Cron) 


SYNOPSIS 
crontab file [-u user] Replace crontab from file 
crontab - [-u user] Replace crontab from stdin 
crontab -1 [user] List crontab for user 
crontab -e [user] Edit crontab for user 
crontab -d [user] D elete crontab for user 
crontab -c dir Specify crontab directory 

DESCRIPTION 


crontab Manipulates the crontab for a particular user. O nly the superuser may specify a different user and/or crontab 
directory. Generally, the -e option isused to edit your crontab. crontab will use /usr/bin/vi or the editor specified by your 
VISUAL environment variableto edit the crontab. 


Unlike other crond/crontabs, this crontab does not try to do everything under the sun. Frankly, a shell script is much more 
able to manipulate the environment than cron, and | see no particular reason to use the user’s shell (from his password entry) 
to run cron commands when this requires special casing of nonuser crontabs, such as those for UUCP. When a crontab 
command isrun, this crontab runsit with /bin/sh and sets up only three environment variables: user, HOME, and SHELL. 


crond automatically detects changes in thetime Reverse-indexed time changes less then an hour old will NOT rerun crontab 
commands already issued in the recovered period. Forward-indexed changes less then an hour into the future will issue 
missed commands exactly once C hanges greater then an hour into the past or future cause crond to resynchronize and not 
issue missed commands. N o attempt will be made to issue commands lost due to a reboot, and commands are not reissued if 
the previously issued command is still running. For example, if you havea crontab Command sleep 70 that you wish to run 
oncea minute, cron will only be able to issue the command once every two minutes. If you do not like this feature, you can 
run your commands in the background with an a. 


cgplit 


The crontab format is roughly similar to that used by vixiecron, but without complex features. Individual fields may contain 
atime atimerange, atime range with a skip factor, a symbolic range for the day of week and month in year, and additional 
subranges delimited with commas. Blank lines in the crontab or lines that begin with a hash (#) are ignored. If you specify 
both a day in the month and a day of week, the result is effectively ord; the crontab entry will be run on the specified day of 
week and on the specified day in the month. 

# MIN HOUR DAY MONTH DAYOFWEEK COMMAND 


# at 6:10 a.m. every day 
10 6 ***date 


# every two hours at the top of the hour 
@ */2 ***date 


Fe 


every two hours from 11p.m. to 7a.m., and at 8a.m. 
23-7/2,8 ***date 


Se 


te 


at 11:00 a.m. on the 4th and on every mon, tue, wed 
@ 11 4 * mon-wed date 


Fe 


4:00 a.m. on january 1st 
4 1 jan *date 


S 


# once an hour, all output appended to log file 
0 41 jan *date>>/var/log/messages 2>&1 


Thecommand portion of thelineisrun with /bin/sh -c <command>, and may therefore contain any valid Bourne shell 
command. A common practiceis to run your command with exec to keep the process table uncluttered. It is also common to 
redirect output to alog file If you do not, and the command generates output on stdout or stderr, the result will be mailed 
to the user in question. If you use this mechanism for special users, such as UUCP, you may want to create an alias for the 
user to direct the mail to someone else, such as root or postmaster. 


Internally, this cron uses a quick indexing system to reduce CPU overhead when looking for commands to execute Several 
hundred crontabs with several thousand entries can be handled without using noticeable CPU resources. 


BUGS 


Ought to be able to have several crontab files for any given user, as an organizational tool. 


AUTHOR 


M atthew D illon (dillon@apollo.west.oic.com) 
1 May1994 
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cesplit— Split a file into sections determined by context lines 


SYNOPSIS 


csplit [-sqkz] [-f prefix] [-b suffix] [-n digits] [—prefix=prefix] 
[—suffix-format=suffix] [—digits=digits] [—quiet] [—silent] 
[—keep-files] [—elide-empty-files] [—help] [—version] 

file pattern... 


DESCRIPTION 


This manual page documents the GN U version of csplit. csplit creates zero or more output files containing sections of the 
given input file, or the standard input if the name - is given. By default, csp1it prints the number of bytes written to each 
output file after it has been created. 


Part |: User Commands 


The contents of the output files are determined by the pattern arguments. An error occursif a pattern argument refers to a 
nonexistent line of the input file, such as if no remaining line matches a given regular expression. After all the given patterns 
have been matched, any remaining output is copied into one last output file. The types of pattern arguments are 


line Create an output file containing the current line up to (but not including) line 1ine (a positive 
integer) of the input file If followed by a repeat count, also create an output file containing the 
next line lines of the input file once for each repeat. 

/regexp/ [offset] Create an output file containing the current line up to (but not including) the next line of the 
input file that contains a match for regexp. T he optional offset isa+ or - followed by a positive 
integer. If it is given, the input up to the matching line plus or minus offset is put into the output 
file, and the line after that begins the next section of input. 





%regexp%[ offset] Like the previous type, except that it does not create an output file, so that section of theinput file 
is effectively ignored. 
{repeat -count} Repeat the previous pattern repeat -count (a positive integer) additional times. An asterisk may be 


given in place of the (integer) repeat count, in which case the preceding pattern is repeated as many 
times as necessary until theinput is exhausted. 


The output filenames consist of a prefix followed by a suffix. By default, the suffix is merely an ascending linear sequence of 
two-digit decimal numbers starting with 00 and ranging up to 99; howeve,, this default may be overridden by either the — 
digits option or by the —suffix-format option. (See “O ptions,” next.) In any case, concatenating the output filesin sorted 
order by filename produces the original input file, in order. The default output filename prefix is xx. 


By default, if csp1it encounters an error or recaves a hangup, interrupt, quit, or terminate signal, it removes any output files 
that it has created so far before it exits. 


OPTIONS 


-f, —prefix=prefix Useprefix asthe output filename prefix string. 

-b, —suffix-format=suffix Usesuffix asthe output filename suffix string. W hen this option is specified, the suffix string 
must include exactly one printt(3) style conversion specification (such as%q, possibly including 
format specification flags, afield width, a precision specifications, or all of these kinds of 
modifiers). The conversion specification must be suitable for converting a binary integer 
argument to readable form. Thus, only d, i, u, 0, x, and x format specifiers are allowed. The 
entire suffix string is given (with the current output file number) to sprintf(3) to form the 
filename suffixes for each of the individual output files in turn. N ote that when this option is 
used, the —digits option isignored. 

, —digits=digits Use output filenames containing numbe’s that are di gi ts digits long instead of the default 2. 

-k, —keep-files Do not remove output files when errors are encountered. 

-z, —elide-empty-files Suppress the generation of zero-1length output files. (In cases where the section ddimiters of the 
input file are supposed to mark the first lines of each of the sections, the first output file will 
generally be a zero-1ength file unless you use this option.) N ote that the output file sequence 
numbers will always run consecutively, starting from 0, even in cases where zero- length output 
sections are suppressed due to the use of this option. 

-s, -q, —Silent, —quiet Do not print counts of output file sizes. 

—help Print a usage message and exit with anonzero status. 

—version Print version information on standard output, then exit. 


= 
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ctags 


ctags—Generates tags and (optionally) refs files 


SYNOPSIS 


ctags [-BSstvraT] filesnames... 


DESCRIPTION 


ctags generates the tags and refs files from a group of C sourcefiles. The tags file is used by the elvis :tag command, 
control-] command, and -t option. T he refs file is sometimes used by the ref(1) program. 


Each C source file is scanned for #define statements and global function definitions. T he name of the macro or function 
becomes the name of a tag. For each tag, alineis added to the tags file that contains the following: 


m Thenameof thetag 

mA tab character 

m Thenameof thefile containing thetag 

mA tab character 

m A way to find the particular line within the file 


Thefilenames list will typically be thenames of all C source filesin the current directory, like this: 
$ ctags -stv *.[ch] 


OPTIONS 


-B Normally, ctags encloses regular expressions in slashes (/regexp/), which causes elvis to search from the 
top of the file T he -8 flag causes ctags to enclose the regular expressions in question marks (?regexp?) SO 
elvis will search backward from the bottom of thefile. This rarely matters. 

-t Include typedets. A tag will be generated for each user-defined type Also tags will be generated for struct 
and enum names. T ypes are considered to be global if they are defined in a header file, and static if they are 
defined in aC sourcefile. 


“V Include variable declarations. A tag will be generated for each variable, except for those that are declared 
inside the body of a function. 
-s Include static tags. ctags will normally put global tags in the tags file, and silently ignore the static tags. 


This flag causes both global and static tags to be added. The name of a static tag is generated by prefixing 
the name of the declared item with the name of the file where it is defined, with a colon in between. For 
example, static foo(){} in bar.c resultsin a tag named bar.c:foo. 
-S Include static tags, but make them look like global tags. M ost tags-aware programs don’t like the 
filename: tagname tags produced by the -s flag, so -s was added as an alternative. If elvis and ref arethe 
only programs that read the tags file, then you don’t need -s; otherwise you do. 
-P This causes ctags to generate both tags and refs. Without -r, it would only generate tags. 
-a Append to tags, and maybe refs. Normally, ctags overwrites these files each timeit is invoked. T his flag is 
useful when you havetoo many filesin the current directory for you to list then on a single command 
line it allows you to split the arguments among several invocations. 
-T This flag isn’t available on all systans. UNIX hasit, but most others don’t. The -T flag prevents ctags 
from generating a tags file T his is useful when you want to generate a refs without changing tags. 











FILES 
tags A cross-reference that lists each tag name, the name of the source file that containsit, and away to locatea 
particular line in the source file 
refs The refs file contains the definitions for each tag in the tags file and very little else. T hisfilecan be 


useful, for example, when licensing restrictions prevent you from making the source code to the standard 
C library readable by everybody, but you still want everybody to know what arguments the library 
functions need. 
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BUGS 


ctags issensitiveto indenting and line breaks. C onsequently, it might not discover all of the tags in a file that is formatted in 
an unusual way. 


SEE ALSO 


elvis(1), refs(1) 


AUTHOR 


Steve Kirkendall (kirkenda@cs.pdx.edu) 


Cu 

cu— Call up another systen 
SYNOPSIS 

cu [ options ] [ system | phone | “dir" ] 
DESCRIPTION 


The cu command is used to call up another system and act as a dial in terminal. It can also do simple file transfers with no 
error checking. 


cu takes a single argument, besides the options. If the argument is the string dir, cu will makea direct connection to the port. 
This may only be used by users with write access to the port, as it permits reprogramming the moden. 


O therwise, if the argument begins with a digit, it is taken to be a phone number to call. O therwise, it is taken to be the name 
of a system to call. The-z or —system option may be used to namea system beginning with a digit, and the -c or —phone 
option may be used to name a phone number that does not begin with adigit. 


cu locates a port to usein the UUCP configuration files. If a simple system name is given, it will select a port appropriate for 
that systen. The-p, —port, -1, —line, -s, and —speed options may be used to control the port selection. 


W hen aconnection ismade to the remote system, cu forks into two processes. O ne reads from the port and writes to the 
terminal, while the other reads from the terminal and writes to the port. 


cu provides several commands that may be used during the conversation. The commands all begin with an escape character, 
initially ~ (tilde). T he escape character is only recognized at the beginning of aline To send an escape character to the 
remote system at the start of aline it must be entered twice All commands areeithe a single character or aword beginning 
with % (percent sign). 


cu recognizes the following commands: 


; Terminate the conversation. 
“1 command Run command in ashal. If command isempty, starts up a shall. 


“$ command Run command, sending the standard output to the renote system. 

“1 command Run command, taking the standard input from the renote system. 

“+ command Run command, taking the standard input from the remote system and sending the standard 
output to the remote system. 

“#, “%break Send a break signal, if possible. 

“ce directory, “%cd directory © Changethelocal directory. 

“> file Send afile to the remote system. T his just dumps the file over the communication line It is 
assumed that the remote system is expecting it. 

“< Receive a file from the remote system. T his prompts for the local filevame and for the 


remote command to execute to begin the file transfer. It continues accepting data until the 
contents of the eofread variable are sean. 


“p from to, “put from to 


“t from to, “stake from to 


“s variable value 
“! variable 

“2 

“snostop 

“sstop 

“v 


“2 


escape 


delay 


eol 


binary 


binary -prefix 


echo-check 


echonl 
timeout 


kill 
resend 
eofwrite 


eofread 


verbose 


OPTIONS 
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Send afile to aremoteU NIX system. This runs the appropriate commands on the remote 
system. 


Retrievea file from a remote UNIX system. T his runs the appropriate commands on the 
remote system. 


Sé acu variable to the given value. If value isnot given, the variable is set to True. 

Se acu variable to False. 

Suspend the cu session. Thisis only supported on some systans. On systems for which *z 
may be used to suspend a job, ~*z will also suspend the session. 

Turn off xon/xorF handling. 

Turn on xon/xorr handling. 

List all the variables and their values. 

List all commands. 


cu also supports several variables. They may be listed with the -v command, and set with the 
~s or ~! commands. 


The escape character. Initially ~ (tilde). 


If this variable is true, cu will delay for asecond after recognizing the escape character before 
printing the name of the local system. T he default is True. 


The list of characters which are considered to finish a line. The escape character is only 
recognized after one of these is sen. The default is carriage return, “u, “Cc, “0, °D, *S, °Q, *R. 


W hether to transfer binary data when sending a file. If thisis False, then newlines in the file 
being sent are converted to carriage returns. T he default is False. 


A string used before sending a binary character in a file transfer, if the binary variable is 
True. T he default is *z. 


W hether to check file transfers by examining what the remote system echoes back. This 
probably doesn’t work very well. The default is False. 


The character to look for after sending each linein a file The default is carriage return. 


The timeout to use, in seconds, when looking for a character, ather when doing echo 
checking or when looking for the echon1 character. T he default is 30. 


The character to use to ddete a line if the echo check fails. The default is *u. 
The number of times to resend a lineif the echo check continues to fail. The default is 10. 
Thestring to write after sending a file with the ~> command. T he default is *p. 


Thestring to look for when receiving a file with the ~< command. The default is $, which is 
intended to be atypical shal prompt. 


W hethe to print accumulated information during a file transfer. T he default is True. 


The following options may be given to cu: 


-e, —parity=even 
-0, —parity=odd 
—parity=none 

-h, —halfduplex 


-Z system, —system system 


-c phone- number, —phone phone- number 


-p port, —port port 
-a port 


-l line, —line line 


Use even parity. 

Use odd parity. 

Useno parity. No parity is also used if both -e and -o aregiven. 

Echo characters locally (half-duplex mode). 

The system to call. 

The phonenumbe to call. 

N ame the port to use 

Equivalent to —port port. 

N ame the line to use by giving a devicename T his may be used to dial out on 


ports that are not listed in the UU CP configuration files. W rite access to the device 
is required. 
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-s speed, —speed speed 
-# 

-n, —prompt 

-d 

-x type, —debug type 


-I file, —config file 


-v, —version 


—help 


BUGS 


This program does not work very wal. 


FILES 


The speed (baud rate) to use. 

Where # isanumbe,, equivalent to —speed #4. 

Prompt for the phone number to use. 

Enter debugging mode. Equivalent to -debug all. 

Turn on particular debugging types. The following types are recognized: abnormal, 
chat, handshake, uucpproto, proto, port, config, spooldir, execute, incoming, 
outgoing. O nly abnormal, chat, handshake, port, config, incoming and outgoing are 
meaningful for cu. M ultiple types may be given, separated by commas, and the — 
debug option may appear multiple times. A number may also be given, which will 
turn on that many types from the foregoing list; for example, —debug 2 is 
equivalent to —debug abnormal,chat. —debug all may be used to turn on all 
debugging options. 

Sé& configuration file to use This option may not be available, depending upon 
how cu was compiled. 

Report version information and exit. 

Print ahap message and exit. 


The filename may be changed at compilation time so thisis only an approximation. Configuration file 


/usr/lib/uucp/config 


AUTHOR 


lan Lance T aylor (ian@airs.com) 


cut 


cut— Remove sections from each | 


SYNOPSIS 


cut {-b byte-list, —bytes=byte - 
cut {-c character-list, —charac 


cut {-f field-list, —fields=fie 
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ine of files 


ist} [-n] [—help] [—version] [file...] 
ters=character-list} [—help] [—version] [file...] 


d-list} [-d delim] [-s] [—delimiter=del i m] 


[—only-delimited] [—help] [—version] [file...] 


DESCRIPTION 


This manual page documents the GN U version of cut. cut prints sections of each line of each input file, or the standard 
input if no files are given. A filename of - means standard input. T he sections to be printed are selected by the options. 


OPTIONS 


Thebyte-list,character-list, andfield-list options are one or more numbers or ranges (two numbers separated by a 
dash) separated by commas. T hefirst byte, character, and field are numbered 1. Incomplete ranges may be given: -m means 1- 
m; n- means n through end of line or last field. 


= 


-b, —bytes byte-list Print only the bytes in positions listed in byte-list. Tabs and backspaces are treated like 
any other character; they take up one byte 

-c, —characters character-list Print only characters in positions listed in character-list. T hesameas -b for now, but 
internationalization will change that. T abs and backspaces are treated like any other 
character; they take up one character. 








-f, —fields field-list Print only the fields listed in field-list. Fidds are separated by Tas by default. 
-d, —delimiter delim For -f, fields are separated by the first character in de! i m instead of by Tas. 

-n Do not split multibyte characters (no-op for now). 

-s, —only-delimited For -f, do not print lines that do not contain the field separator character. 
—help Print a usage message and exit with anonzevo status. 

—version Print version information on standard output then exit. 
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CVS 


evs— Concurrent Versions System 


SYNOPSIS 


cvs [ cvs_options ] cvs-command [ command_options ][command_args ] 


DESCRIPTION 


evs iSafront end to the res(1) revision control system, which extends the notion of revision control from a collection of files 
in asingle directory to a hierarchical collection of directories consisting of revision controlled files. T hese directories and files 
can be combined together to form a software rd ease. cvs provides the functions necessary to manage these software releases 
and to control the concurrent editing of source files among multiple software developers. 


cvs keeps a single copy of the master sources. This copy is called the source repository; it contains all the information to 
permit extracting previous software releases at any time based on either a symbolic revision tag, or a date in the past. 


ESSENTIAL COMMANDS 


evs provides a rich variety of commands (cvs_command in the Synopsis), each of which often has a wealth of options, to satisfy 
the many needs of source management in distributed environments. H owever, you don’t have to master every detail to do 
useful work with evs; in fact, five commands are sufficient to use (and contribute to) the source repository. 


cvs checkout modules... A necessary preliminary for most cvs work: creates your private copy of the source for 
modules (named collections of source you can also use a path relative to the source 
repository here). You can work with this copy without interfering with others’ work. At 
least one subdirectory level is always created. 

cvs update Execute this command from within your private source directory when you wish to 
update your copies of source files from changes that other developers have made to the 
source in the repository. 

cvs add file... Use this command to enroll new files in cvs records of your working directory. T he files 
will be added to the repository the next time you run cvs commit. N ote You should use 
the cvs import command to bootstrap new sources into the source repository. cvs add is 
only used for new files to an already checked-out module 


cvs remove file... Use this command (after erasing any files listed) to declare that you wish to eliminate 
files from the repository. The removal does not affect others until you run cvs commit. 
cvs commit file... Use this command when you wish to “publish” your changes to other developers, by 


incorporating them in the source repository. 
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OPTIONS 


Thecvs command line can include cvs_options, which apply to the overall cvs program; acvs_command, which specifies a 
particular action on the source repository; and command_options and command_arguments to fully specify what the cvs_command 


will do. 


You must be careful of precisdy where you place options rdativeto thecvs_command. T hesameoption can mean different 
things depending on whether it isin thecvs_options position (to the left of acvs command) or in the command_options 
position (to the right of acvs command). 


Thee are only two situations where you may omit cvs_command: cvs -H OF cvs -help elicits a list of available commands, and 
cvs -v OF cvs -version displays version information on cvs itself. 


CVS OPTIONS 


As of rdease 1.6, cvs supports GN U style long options as well as short options. O nly afew long options are currently 
supported; these are listed in brackets after the short options whose functions they duplicate. 


U se these options to control the overall cvs program: 


-H [-help] 
-Q 
-q 
-b bindir 


-d CVS_root_directory 


-e editor 


-v [-version] 


-W 


-Z compression-| evel 


Display usage information about the specified cvs command (but do not actually execute the 
command). If you don’t specify acommand name, cvs -H displays a summary of all the 
commands available 

Causes the command to be really quiet; the command will generate output only for serious 
problems. 

Causes the command to be somewhat quiet; informational messages, such as reports of 
recursion through subdirectories, are suppressed. 

Usebindir asthe directory where RCS programs are located. O verrides the setting of the rcsBIN 
environment variable. This value should be specified as an absolute pathname 
Usecvs_root_directory astheroot directory pathname of the master RCS source repository. 
Overrides the setting of the cvs-rooT environment variable. T his value should be specified as an 
absolute pathname. 

Useeditor to enter revision log information. O verrides the setting of the cvsep1Tor and the 
EDITOR environment variables. 

Do not read the evs startup file (~/.cvsrc). 

Do notlog the cvs_command in the command history (but execute it anyway). See the descrip- 
tion of the history command for information on command history. 

Do not change any files. Attempt to execute the cvs_command, but only to issue reports; do 
not renove, update, or merge any existing files, or create any new files. 

Trace program execution; display messages showing the steps of cvs activity. Particularly useful 
with -n to explore the potential impact of an unfamiliar command. 

M akes new working files read-only. Same effect asif the cvs-reaD environment variable is set. 
Displays version and copyright information for cvs. 

M akes new working files read-write (default). O verrides the setting of the cvsreap environment 
variable. 

W hen transferring files across the network use gzip with compression level compression-level to 
compress and decompress data as it is transferred. Requires the presence of theGN U gzip 
program in the current search path at both ends of the link. 


é 
USAGE 


Except when requesting general help with cvs -H, you must specify a cvs_command to cvs to select a specific release control 
function to perform. Each cvs command accepts its own collection of options and arguments. H owever, many options are 
available across several commands. You can display a usage summary for each command by specifying the -x option with the 
command. 


CVS STARTUP FILE 


Normally, when cvs starts up, it reads the .cvsrc file from the home directory of the user reading it. T his startup procedure 
can be turned off with the -+ flag. 


The .cvsrc file lists cvs commands with alist of arguments, one command pe line For example, the following line in 
-CVSre. 


diff -c 
will mean that the cvs diff command will always be passed the -c option in addition to any other options that are specified 
in the command line (in this case, it will have the effect of producing context sensitive diffs for all executions of cvs diff ). 
CVSCOMMAND SUMMARY 
H ere are brief descriptions of all the cvs commands: 


add Add a new file or directory to the repository, pending acvs commit on the same file. Can only bedone 
from within sources created by apreviouScvs checkout invocation. Use cvs import to place whole new 
hierarchies of sources under cvs control. (D oes not directly affect repository; changes working 


directory.) 

admin Execute RCS control functions on the source repository. (C hanges repository directly; uses working 
directory without changing it.) 

checkout M ake a working directory of source files for editing. (Creates or changes working directory.) 

commit Apply to the source repository changes, additions, and deletions from your working directory. 
(C hanges repository.) 

diff Show differences between files in working directory and source repository, or between two revisions in 
source repository. (D oes not change either repository or working directory.) 

export Prepare copies of a set of source files for shipment off site. Differs from cvs checkout in that no cvs 


administrative directories are created (and therefore cvs commit cannot be executed from a directory 
prepared with cvs export), and a symbolic tag must be specified. (D oes not change repository; creates 
directory similar to working directories). 

history Show reports on cvs commands that you or others have executed on a particular file or directory in the 
source repository. (D oes not change repository or working directory.) History logs are kept only if 
enabled by creation of the scvsrooT/cvsRooT/history file; see cvs(5). 


import Incorporate a set of updates from off-site into the source repository, asa “vendor branch.” (C hanges 
repository.) 

log Display RCS log information. (D oes not change repository or working directory.) 

rdiff Prepare a collection of diffs asa patch file between two rdeases in the repository. (D oes not change 
repository or working directory.) 

release Cancel acvs checkout, abandoning any changes. (C an delete working directory; no effect on 
repository.) 

remove Remove files from the source repository, pending acvs commit on the same files. (D oes not directly 
affect repository; changes working directory.) 

rtag Explicitly specify a symbolic tag for particular revisions of files in the source repository. See also cvs 
tag. (Changes repository directly; does not require or affect working directory.) 

status Show current status of files: latest version, version in working directory, whether working version has 


been edited and, optionally, symbolic tags in theRCS file (D oes not change repository or working 
directory.) 
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tag 


update 


Specify a symbolic tag for files in the repository. By default, tags the revisions that were last synchro- 
nized with your working directory. (C hanges repository directly; uses working directory without 
changing it.) 

Bring your working directory up to date with changes from the repository. M erges are peformed 
automatically when possible; a warning is issued if manual resolution is required for conflicting 
changes. (C hanges working directory; does not change repository.) 


COMMON COMMAND OPTIONS 


This section describes the command_options that are available across several cvs commands. N ot all commands support all of 
these options; each option is only supported for commands where it makes sense. H owever, when a command has one of 
these options you can count on the same meaning for the option asin othe: commands. (O ther command options, which 
are listed with the individual commands, may have different meanings from one cvs command to another.) 


The history command is an exception; it supports many options that conflict even with these standard options. 


-D date 


-k kflag 


Use the most recent revision no later than date_spec (asingle argument, date description specifying a 
date in the past). A wide variety of date formats are supported by the underlying RCS facilities, smilar 
to those described in co(1), but not exactly the same. T he date_spec iSinterpreted as being in thelocal 
time zone, unless a specific time zone is specified. T he specification is “sticky” when you use it to make 
a private copy of a source file that is, when you get a working file using -p, cvs records the date you 
specified, so that further updatesin the same directory will use the same date (unless you explicitly 
override it; see the description of the update command). -p is available with the checkout, diff, history, 
export, rdiff, rtag, and update commands. Examples of valid date specifications include the following: 

1 month ago 

2 hours ago 

400000 seconds ago 

last year 

last M onday 

yesterday 

a fortnight ago 

3/31/92 10:00:07 PST 

January 23, 1987 10:05pm 

22:00 GMT 


W hen you specify a particular date or tag to cvs commands, they normally ignore files that do not 
contain the tag (or did not exist on the date) that you specified. U se the -F option if you want files 
retrieved even when there is no match for the tag or date. (T he most recent version is used in this 
situation.) -f is available with these commands: checkout, export, rdiff, rtag, and update. 

H elp; describe the options available for this command. T his is the only option supported for all cvs 
commands. 

Alter the default RCS processing of keywords; all the -k options described in co(1) are available. T he -k 
option is available with the ada, checkout, diff, export, rdiff, aNd update commands. Your kf! ag 
specification is “sticky” when you use it to create a private copy of a source file: that is, when you use 
this option with the checkout Or update commands, cvs associates your selected kf! ag with the file and 
continues to useit with future update commands on the samefile until you specify otherwise 

Some of the more useful kf! ag Sare-ko and - kb (for binary files, only compatible with RCS version 5.7 
or later), and -kv, which is useful for an export where you wish to retain keyword information after an 
import at some othe site 


- 


-1 Local; run only in current working directory, rather than recurring through subdirectories. Available 
with the following commands: checkout, commit, diff, export, remove, rdiff, rtag, status, tag, and 
update. 


This is not the same as the overall cvs -1 option, which you can specify to the left of acvs command. 


-n Do notrun any checkout /commit/tag/update program. (A program can be specified to run on each of 
these activities, in the modules database; this option bypasses it.) Available with the checkout, commit, 
export, and rtag commands. 


This is not the same as the overall cvs -n option, which you can specify to the left of acvs command. 


-P Prune (remove) directories that are enpty after being updated, on checkout, or update. N ormally, an 
empty directory (one that is void of revision-controlled files) is left alone Specifying -P will cause these 
directories to be silently removed from your checked-out sources. T his does not remove the directory 
from therepository, only from your checked out copy. N ote that this option is implied by the -r or -p 
options of checkout and export. 


-p Pipe the files retrieved from the repository to standard output, rather than writing them in the current 
directory. Available with the checkout and update commands. 
-r tag Use the revision specified by the tag argument instead of the default head revision. As well as arbitrary 


tags defined with the tag or rtag command, two special tags are always available: Heap refers to the 
most recent version available in the repository, and Base refers to the revision you last checked out into 
the current working directory. The tag specification is “sticky” when you use this option with cvs 
checkout OF cvs update to make your own copy of afile cvs remembers the tag and continues to use it 
on future update commands, until you specify otherwise. tag can be ather a symbolic or numaiic tag, 
in RCS fashion. Specifying the -q global option along with the -r command option is often useful, to 
suppress the warning messages when the RCS file does not contain the specified tag. -r is available 
with the checkout, commit, diff, history, export, rdiff, rtag, aNd update Commands. 


This is not the same as the overall cvs -r option, which you can specify to the left of acvs command. 


cvs COMMANDS 


H ere (finally) are details on all the cvs commands and the options each accepts. The summary lines at the top of each 
command's description highlight three kinds of things: 


Command O ptionsand Arguments — Special options are described in detail; common command options may appear only 
in thesummary line 

Working Directory, or Repository? Some cvs commands require a working directory to operate; some require a 
repository. Also, some commands change the repository, some change the working 
directory, and some change nothing. 

Synonyms M any commands have synonyms, which you may find easier to renenber (or type) 
than the principal name 
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M add [-k kflag][-m 'message'] files... 


Requires: Repository, working directory 
Changes: W orking directory 
Synonym: new 


Use the add command to create a new file or directory in the RCS source repository. The files or directories specified with 
add must already exist in the current directory (which must have been created with the checkout command). To add a whole 
new directory hierarchy to the source repository (for example, files recaved from a third-party vendor), use the cvs import 
command instead. 


If the argument to cvs add refers to an immediate subdirectory, thedirectory is created at the correct placein theRCS source 
repository, and the necessary cvs administration files are created in your working directory. If the directory already exists in 
the source repository, cvs add still creates the administration filesin your version of the directory. T his allows you to use cvs 
add to add a particular directory to your private sources even if someone else created that directory after your checkout of the 
sources. You can do the following: 

example% mkdir new_directory 


example% cvs add new_directory 
example% cvs update new_directory 


An alternate approach using cvs update might be: 
example% cvs update -d new_directory 
(To add any available new directories to your working directory, it’s probably simpler to use cvs checkout OF cvs update -d.) 


The added files are not placed in the RCS source repository until you use cvs commit to make the change pamanent. Doing 
acvs add on afile that was renoved with thecvs remove command will resurrect the file, if no cvs commit command 
intervened. 


You will have the opportunity to specify a logging message, as usual, when you use cvs commit to make the new file 
permanent. If you'd like to have another logging message associated with just creation of the file (for example, to describe the 
file’s purpose), you can specify it with the -m message option to the add command. 


The -k kflag option specifies the default way that this file will be checked out. Thekfl ag argument is stored in theRCS file 
and can be changed with cvs admin. Specifying -ko isuseful for checking in binaries that shouldn’t havethe RCS id strings 


expanded. 

M admin [rcs-options] files... 
Requires: Repository, working directory 
Changes: Repository 
Synonym: rcs 


Thisis the cvs interface to assorted administrative RCS facilities, documented in rcs(1). cvs admin simply passes all its 
options and arguments to theres command; it does no filtering or other processing. T his command does work recursively, 
however, so extreme care should be used. 


M checkout [options] modules... 


Requires: Repository 
Changes: W orking directory 
Synonyms: co, get 


M ake aworking directory containing copies of the source files specified by modules. You must execute cvs checkout before 
using most of the other cvs commands, since most of them operate on your working directory. 


modules are either symbolic names [themselves defined as the module modules in the source repository; see cvs(5)] for some 
collection of source directories and files, or paths to directories or files in the repository. 


Depending on the modules you specify, checkout may recursively create directories and populate then with the appropriate 
source files. You can then edit these source files at any time (regardless of whether other software developers are editing thar 
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own copies of the sources); update them to include new changes applied by others to thesource repository; or commit your 
work as a permanent change to the RCS repository. 


N ote that checkout is used to create directories. The top-level directory created is always added to the directory where 
checkout is invoked, and usually has the samename as the specified module In the case of a module alias, the created 
subdirectory may have a different name, but you can be sure that it will be a subdirectory, and that checkout will show the 
relative path leading to each file asit is extracted into your private work area (unless you specify the -a global option). 
Running cvs checkout on a directory that was already built by a prior checkout isalso permitted, and has the same effect as 
specifying the -d option to the update command described later. 

The options permitted with cvs checkout include the standard command options -p, -f, -k kflag, -1, -n, -p, -r tag, and -p 
date. In addition to those, you can use several special command options with checkout, as detailed in the following para- 
graphs. 

Use the -a option to reset any sticky tags, dates, or -k options. (If you get a working file using one of the -r, -p, or -k 
options, cvs remembers the corresponding tag, date, OF kflag and continues using it on future updates, use the -a option to 
make cvs forget these specifications, and retrieve the head version of the file). 

The -j branch option merges the changes made between the resulting revision and the revision that it is based on (for 
example, if the tag refers to a branch, cvs will merge all changes made in that branch into your working file). 


With two -j options, cvs will merge in the changes between the two respective revisions. T his can be used to “remove” a 
cetain data from your working file 


In addition, each -j option can contain on optional date specification which, when used with branches, can limit the chosen 
revision to one within a specific date An optional date is specified by adding a colon (:) to the tag. An example might be 
what cvs import tals you to do when you have just imported sources that have conflicts with local changes: 


example% cvs checkout -jTAG:yesterday -jTAG module 


Use the -n option with -a dir to avoid shortening module paths in your working directory. (N ormally, cvs shortens paths as 
much as possible when you specify an explicit target directory.) 


Use the -c option to copy the module file, sorted, to the standard output, instead of creating or modifying any files or 
directories in your working directory. 


Usethe-a dir option to create a directory called dir for the working files, instead of using the module name. Unless you 
also use -n, the paths created under dir will be as short as possible 


Use the -s option to display per-module status information stored with the -s option within the modules file. 


HM commit [-1nR][-m ‘log message’ | -f file][-r revision][files...] 
Requires: W orking directory, repository 
Changes: Repository 
Synonym: ci 


Usecvs commit when you want to incorporate changes from your working source files into the general source repository. 


If you don’t specify particular files to commit, all of the files in your working current directory are examined. commit is 
careful to changein the repository only those files that you have really changed. By default (or if you explicitly specify the -r 
option), filesin subdirectories are also examined and committed if they have changed; you can use the -1 option to limit 
commit to thecurrent directory only. Sometimes you may want to forceafileto be committed even though it is unchanged; 
thisis achieved with the -+ flag, which also has the effect of disabling recursion (you can turn it back on with -r, of course). 


commit verifies that the selected files are up-to-date with the current revisionsin the source repository; it will notify you, and 
exit without committing, if any of the specified files must be made current first with cvs update. commit does not call the 
update command for you, but rather leaves that for you to do when thetimeis right. 








When all is wal, an editor is invoked to allow you to enter a log message that will be written to one or more logging 
programs and placed in the RCS sourcerepository file. You can instead specify the log message on the command line with 
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the -m option, thus suppressing the editor invocation, or use the -F option to specify that the argument file contains the log 
message. 


The -r option can be used to commit to a particular symbolic or numevic revision within the RCS file. For example, to bring 
all your files up to the RCS revision 3.0 (including those that haven’t changed), you might use 


example% cvs commit -r3.0 


evs will only allow you to commit to a revision that is on the main trunk (a revision with a single dot). H owever, you can 
also commit to a branch revision (onethat has an even number of dots) with the -r option. T o create a branch revision, one 
typically use the -b option of the rtag or tag commands. T hen, either checkout OF update can be used to base your sources on 
the newly created branch. From that point on, all commit changes made within these working sources will be automatically 
added to a branch revision, thereby not perturbing mainline devdopment in any way. For example, if you had to create a 
patch to the 1.2 version of the product, even though the 2.0 version is already under development, you might use this: 
example% cvs rtag -b -rFCS1_2 FCS1_2 Patch product_module 

example% cvs checkout -rFCS1_2 Patch product module 

example% cd product module 


[[ hack away ]] 
example% cvs commit 


Say you have ben working on some extremely experimental software, based on whatever revision you happened to checkout 
last week. If others in your group would like to work on this software with you, but without disturbing mainline devdop- 
ment, you could commit your change to a new branch. O thers can then check out your experimental stuff and utilize the full 
benefit of cvs conflict resolution. The scenario might look like this: 

example% cvs tag -b EXPR1 

example% cvs update -rEXPR1 


[[ hack away ]] 
example% cvs commit 


Others would simply do cvs checkout -rEXPR1 whatever_module to work with you on the experimental change. 


M diff [-kl][rcsdiff_options][[-r revl | -D datel][-rrev2 | -D date2]] [files... 
Requires: W orking directory, repository 
Changes: Nothing 


You can compare your working files with revisionsin the source repository, with the cvs diff command. If you don’t specify 
a particular revision, your files are compared with the revisions they were based on. You can also use the standard cvs 
command option -r to specify a particular revision to compare your files with. Finally, if you use -r twice, you can see 
differences between two revisions in therepository. You can also specify -p options to diff against arevision in the past. The 
-r and -p options can be mixed together with at most two options ever specified. 


See resdiff(1) for alist of other accepted options. 


If you don’t specify any files, ditt will display differences for all those files in the current directory (and its subdirectories, 
unless you use the standard option -1) that differ from the corresponding revision in the source repository (that is, files that 
you have changed), or that differ from the revision specified. 


M export [-f 1NnQq] -r rev | -D date [-d dir][-k kflag] module... 
Requires: Repository 
Changes: Current directory 


This command is a variant of cvs checkout; use it when you want a copy of the source for modul e without the cvs administra- 
tive directories. For example, you might use cvs export to prepare source for shipment off-site. T his command requires that 
you specify a date or tag (with -p or -r), so that you can count on reproducing the source you ship to others. 


Theonly nonstandard options are -d dir (write the sourceinto directory dir ) and -n (don’t shorten module paths). T hese 
have the same meanings as the same optionsin cvs checkout. 
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The -kv option is useful when export is used. T his causes any RCS keywords to be expanded such that an import done at 
some other site will not lose the keyword revision information. O ther kf! ag options may be used with cvs export and are 
described in co(1). 


M history [-report ][-flags][-options args ][{files...] 
Requires: The file scvsroot/cvsrooT/history 
Changes: Nothing 


evs keeps a history file that tracks each use of the checkout, commit, rtag, update, and release Commands. You Can use cvs 
history to display this information in various formats. 


evs history USES -f, -1, -n, and -p in ways that conflict with the descriptionsin “Common Command O ptions,” earlier 
in this manual page. 


Several options (shown as [-report ] in the preceding bulleted codeline) control what kind of report is generated: 


-c Report on each time commit was used (that is, each time the repository was modified). 

-m module Report on a particular module. (You can meaningfully use -m more than once on the command line.) 
-0 Report on checked-out modules. 

-T Report on all tags. 

-x type Extract a particular set of record types x from the cvs history. The types are indicated by single letters, 


which you may specify in combination. C ertain commands havea single record type: check-out (type 
0), release (typeF), and rtag (type T). One of four record types may result from an update: w, when the 
working copy of afile is deleted during update (because it was gone from the repository); u, when a 
working file was copied from the repository; ¢, when a merge was necessary and it succeeded; and c, 
when a merge was necessary but collisions were detected (requiring manual merging). Finally, one of 
three record types results from commit: m, when a file was modified; a, when a file is first added; and r, 
whe afileis renoved. 

-e Everything (all record types); equivalent to specifying -xmacFRoGwuT. 

-Z Zone Use time zonezone when outputting history records. The zonename t stands for local time; numeric 
offsets stand for hours and minutes ahead of UTC. For example, +0530 stands for 5 hours and 30 
minutes ahead of (that is, east of) UTC. 


The options shown as -f!ags constrain the report without requiring option arguments: 


-a Show data for all users. (T he default is to show data only for the user executing cvs history.) 

-1 Show last modification only. 

-w Show only the records for modifications done from the same working directory where cvs history iS 
executing. 


Theoptions shown as- options args constrain the report based on an argument: 


-b str Show data back to a record containing the string str in athe the module name, the filename, or the 
repository path. 

-D date Show data sincedate. 

-p repository Show data for a particular source repository (you can specify several -p options on the same command 
line), 

“Prey Show records referring to revisions since the revision or tag named rev appears in individual RCS files. 
Each RCS file is searched for the revision or tag. 

-t tag Show records since tagt ag was last added to the history file. This differs from the -r flag in that it 


reads only the history file, not theRCS files, and is much faster. 
-u name Show records for username. 
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M import [-options] repository vendortag releasetag ... 
Requires: Repository, source distribution directory 


Changes: Repository 
Usecvs import to incorporate an entire source distribution from an outside source (for example, a source vendor) into your 


source repository directory. You can use this command both for initial creation of arepository, and for wholesale updates to 
the module form the outside source 


The repository argument gives a directory name (or a path to a directory) under the CVS root directory for repositories, if 
the directory did not exist, import creates it. 


W hen you use import for updates to source that has been modified in your source repository (since a prior import), it will 
notify you of any files that conflict in the two branches of development; use cvs checkout -j to reconcile the differences, as 
import instructs you to do. 


By default, certain filevames are ignored during cvs import: names associated with CVS administration, or with other 
common source control systems; common names for patch files, object files, archive files, and editor backup files; and other 
names that are usually artifacts of assorted utilities. Currently, the default list of ignored files includes files matching these 
names: 


RCSLOG RCS SCCS 
CVS* cvslog.* 
tags TAGS 
-make.state .nse_depinfo 
He HE, 
-Old *.bak *.BAK *.orig *.rej .del-* 
-a *.0 *.S0 *.Z *.elc *.1n core 
T he outside source is saved in a first-level RCS branch, by default 1.1.1. Updates are leaves of this branch; for example, files 


from the first imported collection of source will be revision 1.1.1.1, then files from the first imported update will be revision 
1.1.1.2, and so on. 


At least three arguments are required. repository isneeded to identify the collection of source. vendortag isatag for the 
entire branch (for example, for 1.1.1). You must also specify at least onerel easet ag to identify the files at the leaves created 
each time you execute cvs import. 


Oneof the standard cvs command options is available: -m message. If you do not specify a logging message with -m, your 
editor is invoked (as with commit) to allow you to enter one 


Thee are three additional special options. 
Use -a to specify that each file's time of last modification should be used for the checkin date and time. 
Use-b branch to specify afirst-levd branch other than 1.1.1. 


Use-1 name to specify filevames that should be ignored during import. You can use this option repeatedly. To avoid 
ignoring any files at all (even those ignored by default), specify -1 !. 


M log [-1] rlog-options [files...] 


Requires: Repository, working directory 
Changes: Nothing 
Synonym: rlog 


Display log information for files. cvs log callsthe RCS utility rog; all the options described in r1og(1) are available 
Among the more useful r1og options are -h to display only the header (including tag definitions, but omitting most of the 
full log); -r to select logs on particular revisions or ranges of revisions; and -d to select particular dates or date ranges. See 
rlog(1) for full explanations. This command is recursive by default, unless the -1 option is specified. 
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M rdiff [-flags][-V vn][-r t{-Dd [-r t2{-D d2]] modules... 
Requires: Repository 
Changes: Nothing 
Synonym: patch 


Builds a Larry W all format patch(1) file between two releases that can be fed directly into the patch program to bring an old 
release up-to-date with the new release. (T his is one of the few cvs commands that operates directly from the repository and 
doesn’t require a prior checkout.) T he aiff output is sent to the standard output device You can specify (using the standard 
-r and -p options) any combination of one or two revisions or dates. If only one revision or date is specified, the patch file 
reflects differences between that revision or date and the current head revisionsin the RCS file 


N ote that if the software release affected is contained in more than one directory, then it may be necessary to specify the-p 
option to the patch command when patching the old sources, so that patch is able to find the files that are located in other 
directories. 

If you use the option -v vn, RCS keywords are expanded according to therules current in RCS version vn (the expansion 
format changed with RCS version 5). 


The standard option f! ags -f and -1 are available with this command. T here are also several special optionst| ags. 


If you use the -s option, no patch output is produced. Instead, a summary of the changed or added files between the two 
releases is sent to the standard output device This is useful for finding out, for example, which files have changed between 
two dates or revisions. 

If you use the -t option, aditt of the top two revisionsis sent to the standard output device Thisis most useful for seeing 
what the last change to a file was. 


If you use the -u option, the patch output uses the newer unidiff format for context diffs. 
You can use -c to explicitly specify the diff -c form of context airs (which is the default), if you like 


M release [-dQq] modules... 
Requires: W orking directory 
Changes: W orking directory, history log 
This command is meant to safely cancel the effect of cvs checkout. Since cvs doesn’t lock files, it isn’t strictly necessary to use 


this command. You can always simply delete your working directory, if you like but you risk losing changes you may have 
forgotten, and you leave no trace in the cvs history file that you’ve abandoned your checkout. 


Usecvs release to avoid these problems. T his command checks that no uncommitted changes are present; that you are 
executing it from immediately above, or inside, acvs working directory; and that the repository recorded for your files is the 
same as the repository defined in the module database. 

If all these conditions are true, cvs release leaves arecord of its execution (attesting to your intentionally abandoning your 
checkout) in the cvs history log. 


You can use the -d flag to request that your working copies of the source files be deleted if the release succeeds. 


M remove [-1R][files...] 
Requires: W orking directory 
Changes: W orking directory 
Synonyms: rm, delete 


Use this command to declare that you wish to remove files from the source repository. Like most cvs commands, cvs remove 
works on filesin your working directory, not directly on the repository. As a safeguard, it also requires that you first erase the 
specified files from your working directory. 


The files are not actually removed until you apply your changes to the repository with commit; at that point, the correspond- 
ing RCS filesin the source repository are moved into the attic directory (also within the source repository). 
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This command is recursive by default, scheduling all physically removed files that it finds for renoval by the next commit. Use 
the -1 option to avoid this recursion, or just specify that actual files that you wish remove to consider. 


M rtag [-f alnRQq][-b][-d][-r tag | -D date] symbolic_tag modules... 


Requires: Repository 
Changes: Repository 
Synonym: rfreeze 


You can use this command to assign symbolic tags to particular, explicitly specified source versions in the repository. cvs 
rtag works directly on the repository contents (and requires no prior checkout). Usecvs tag instead, to base the selection of 
versions to tag on the contents of your working directory. 


In general, tags (often the symbolic names of software distributions) should not be removed, but the-d option is available as 
a means to remove completely obsolete symbolic names if necessary (as might be the case for an Alpha release, say). 


evs rtag will not movea tag that already exists. W ith the -F option, however, cvs rtag will rdocate any instance of 
symbolic_tag that already exists on that file to the new repository versions. Without the -F option, attempting to use cvs 
rtag to apply a tag that already exists on that file will produce an error message. 


The -b option makes the tag a branch tag, allowing concurrent, isolated devdopment. Thisis most useful for creating a patch 
to apreviously rdeased software distribution. 


You can use the standard -r and -p options to tag only those files that already contain a certain tag. This method would be 
used to rename a tag: tag only the files identified by the old tag, then delete the old tag, leaving the new tag on exactly the 
same files as the old tag. 


rtag executes recursively by default, tagging all subdirectories of modules you specify in the argument. You can restrict its 
operation to top-level directories with the standard -1 option; or you can explicitly request recursion with -r. 


The modules database can specify a program to execute whenever a tag is specified; a typical use is to send electronic mail to 
a group of interested parties. |f you want to bypass that program, use the standard -n option. 


Use the -a option to have rtag look in the Attic for removed files that contain the specified tag. The tag is ranoved from 
these files, which makes it convenient to reuse a symbolic tag as devdopment continues (and files get renoved from the 
upcoming distribution). 
M > status [-1RqQ][-v][files ...] 

Requires: W orking directory, repository 

Changes: Nothing 


Display a brief report on the current status of files with respect to the source repository, including any sticky tags, dates, or -k 
options. (Sticky options will restrict how cvs update operates until you reset them; see the description of cvs update -A.... 


You can also use this command to anticipate the potential impact of acvs update on your working source directory. If you 
do not specify any files explicitly, reports are shown for all files that cvs has placed in your working directory. You can limit 
the scope of thissearch to the current directory itself (not its subdirectories) with the standard -1 option flag; or you can 
explicitly request recursive status reports with the -r option. 


The -v option causes the symbolic tags for the RCS file to be displayed as well. 


M tag [-1QqR][-F][-b][-d][-r tag | -D date][-f] symbolic tag [files ...] 


Requires: W orking directory, repository 
Changes: Repository 
Synonym: freeze 


Use this command to assign symbolic tags to the nearest repository versions to your working sources. The tags are applied 
immediately to the repository, as with rtag. O neuse for tags is to record a “snapshot” of the current sources when the 
software freeze date of a project arrives. As bugs are fixed after the freeze date, only those changed sources that are to be part 
of the release need be retagged. 
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The symbolic tags are meant to pamanently record which revisions of which files were used in creating a software distribu- 
tion. The checkout, export, and update commands allow you to extract an exact copy of a tagged release at any timein the 
future, regardless of whether files have been changed, added, or removed since the rd ease was tagged. 


You can use the standard -r and -p options to tag only those files that already contain a certain tag. This method would be 
used to rename a tag: tag only the files identified by the old tag, then delete the old tag, leaving the new tag on exactly the 
same files as the old tag. 


Specifying the -+ flag in addition to the -r or -p flags will tag those files named on the command line even if they do not 
contain the old tag or did not exist on the specified date. 


By default (without a -r or -p flag), the versions to be tagged are supplied implicitly by the cvs records of your working files’ 
history rather than applied explicitly. 


If you use cvs tag -d symbolic tag..., thesymbolic tag you specify is ddeted instead of bang added. 


Bevery certain of your ground before you ddete a tag; doing this effectivay discards some historical information, which 
may later turn out to have been valuable 


evs tag will not movea tag that already exists. With the -F option, however, cvs tag will relocate any instance of symbolic 
tag that already exists on that file to the new repository versions. Without the -F option, attenpting to use cvs tag to apply a 
tag that already exists on that file will produce an error message. 


The -b option makes the tag a branch tag, allowing concurrent, isolated development. T his is most useful for creating a patch 
to a previously rdeased software distribution. 


Normally, tag executes recursively through subdirectories; you can prevent this by using the standard -1 option, or specify 
the recursion explicitly by using -r. 


MM update [-Adf 1PpQqR][-d][-r tag{-D date] files... 
Requires: Repository, working directory 
Changes: W orking directory 


After you've run checkout to create your private copy of source from the common repository, other developers will continue 
changing the central source. From timeto time, when it is convenient in your devdopment process, you can use the update 
command from within your working directory to reconcile your work with any revisions applied to the source repository 
since your last checkout or update. 


update keaps you informed of its progress by printing a line for each file, prefaced with one of the characters u, A, R, M, C, Or 2 
to indicate the status of the file: 


U file The file was brought up-to-date with respect to the repository. T his is done for any file that exists in 
the repository but not in your source, and for files that you haven't changed but are not the most 
recent versions available in the repository. 

Afile The file has been added to your private copy of the sources, and will be added to the RCS source 
repository when you run cvs commit on thefile. Thisis areminder to you that the file needs to be 
committed. 

R file The file has been removed from your private copy of the sources, and will be renoved from theRCS 
source repository when you run cvs commit on the file. Thisisareminder to you that the file needs to 
be committed. 

M file The file is modified in your working directory. m can indicate one of two states for a file you're working 
on: either there were no modifications to the same file in the repository, so that your file renains as 
you last saw it; or there were modificationsin the repository as well asin your copy, but they were 
merged successfully, without conflict, in your working directory. 
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C file A conflict was detected whiletrying to merge your changes to fi! e with changes from the source 
repository. file (the copy in your working directory) is now the output of the rcsmerge(1) command 
on the two versions; an unmodified copy of your file is also in your working directory, with thename 
.#file.version, where version isthe RCS revision that your modified file started from. (N ote that 
some systems automatically purge files that begin with .# if they havenot been accessed for a few days. 
If you intend to keep a copy of your original file, it isa very good idea to renameit.) 

2 file file isin your working directory, but does not correspond to anything in the source repository, and is 
not in the list of files for cvs to ignore; see the description of the -1 option. 


Use the -a option to reset any sticky tags, dates, or -k options. (If you get a working copy of a file by using one of the -r, -, 
or -k options, cvs remembers the corresponding tag, date, Or kflag and continues using it on future updates; use the -a 
option to make cvs forget these specifications, and retrieve the head version of the file). 


The -jbranch option merges the changes made between the resulting revision and the revision that it is based on. (For 
example, if the tag refers to a branch, cvs will merge all changes made in that branch into your working file.) 


With two -j options, cvs will merge in the changes between the two respective revisions. T his can be used to “remove” a 
cetain data from your working file For example, if the file foo.c is based on revision 1.6 and | want to remove the changes 
made between 1.3 and 1.5, | might do this: 


example% cvs update -j1.5 -j1.3 foo.c # note the order... 


In addition, each -j option can contain on optional date specification which, when used with branches, can limit the chosen 
revision to one within a specific date An optional date is specified by adding a colon (:) to the tag: 


-jSymbolic Tag:Date Specifier 


Use the -a option to create any directories that exist in therepository if they're missing from theworking directory. 

(N ormally, update acts only on directories and files that were already enrolled in your working directory.) T his is useful for 
updating directories that were created in the repository since the initial checkout; but it has an unfortunate side effect. If you 
ddiberately avoided certain directories in the repository when you created your working directory (either through use of a 
module name or by listing explicitly the files and directories you wanted on the command line), then updating with -d will 
create those directories, which may not be what you want. 


Use -1 name to ignore files whosenames match name (in your working directory) during the update. You can specify -1 more 
than onceon the command line to specify several files to ignore. By default, update ignores files whose names match any of 
the following: 

RCSLOG RCS SCCS 

CVS* cvslog.* 

tags TAGS 

-make.state .nse_depinfo 

"oe HR, 

-old *.bak *.BAK *.orig *.rej .del-* 

-a *.0 *.so *.Z *.elc *.1n core 


Use -1! to avoid ignoring any files at all. 
The standard cvs command options -f, -k, -1, -P, -p, and -r arealso available with update. 


FILES 
For more detailed information on cvs supporting files, see cvs(5). 
Files in home directories: 


.cvsrc The cvs initialization file. Lines in this file can be used to specify default options for each cvs 
command. For example theline ditt -c will ensure that cvs diff is always passed the -c option in 
addition to any other options passed on the command line 

.cvswrappers Specifies wrappers to be used in addition to those specified in the cvsroot/cvswrappers filein the 
repository. 


Files in working directories: 


CVS 

CVS/Entries 
CVS/Entries.Backup 
CVS/Entries.Static 
CVS/Root 


CVS/Repository 
CVS/Tag 


CVS/Checkin. prog 
CVS/Update. prog 


Files in source repositories: 


$CVSROOT / CVSROOT 
CVSROOT/commitinfo,v 
CVSROOT/cvswrappers,v 


CVSROOT/editinfo,v 
CVSROOT/history 
CVSROOT/loginfo,v 
CVSROOT/modules,v 
CVSROOT/rcsinfo,v 
CVSROOT/taginfo,v 
MODULE /Attic 
#cvs. lock 
#covs.tfl.pid 
#ovs.rfl.pid 
#cvs.wfl.pid 


ENVIRONMENT VARIABLES 


CVSROOT 


CVSREAD 


RCSBIN 


CVSEDITOR 


CVS_IGNORE_REMOTE_ROOT 
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A directory of cvs administrative files. D o not delete. 
List and status of files in your working directory. 

A backup of cvs/Entries. 

Flag: do not add more entries on cvs update. 


Pathname to the repository (cvsroot) location at the time of checkout. T his file is used instead 
of the cvsroot environment variable if the environment variable is not set. A warning message 
will be issued when the contents of this file and the cvsroot environment variable differ. T he 
file may be overridden by the presence of thecvs_IGNORE_REMOTE_ROOT environment variable 


Pathname to the corresponding directory in the source repository. 


Contains the per-directory sticky tag or date information. This file is created/updated when you 
specify -r or -p to the checkout Or update commands, and no files are specified. 


Name of program to run on cvs commit. 
N ame of program to run on cvs update. 


Directory of global administrative files for repository. 
Records programs for filtering cvs commit requests. 


Records cvs wrapper commands to be used when checking files into and out of the repository. 
W rappers allow the file or directory to be processed on the way in and out of cvs. T heintended 
uses are many; one possible use would be to reformat a C file before the file is checked in, so all 
of thecodein the repository looks the same 


Records programs for editing/validating cvs commit log entries. 

Log file of cvs transactions. 

Records programs for piping cvs commit log entries. 

Definitions for modules in this repository. 

Records pathnames to templates used during acvs commit operation. 
Records programs for validating/logging cvs tag and cvs rtag operations. 
Directory for removed source files. 

A lock directory created by cvs when doing sensitive changes to the RCS source repository. 
Temporary lock file for repository. 

A read lock. 

A write lock. 


Should contain the full pathname to the root of the cvs source repository (where the RCS files 
are kept). Thisinformation must be availableto cvs for most commands to execute; if cvsRooT 
isnot set, or if you wish to override it for one invocation, you can supply it on the command 
lin@ cvs -d cvsroot cvs command.... YOu may not need to set cvsroor if your cvs binary has the 
right path compiled in; usecvs -v to display all compiled-in paths. 

If thisis set, checkout and update will try hard to make thefiles in your working directory read- 
only. W hen thisis not set, the default behavior isto permit modification of your working files. 
Specifies the full pathname where to find RCS programs, such as co(1)and ci(1). If not set, a 
compiled-in value is used; see the display from cvs -v. 

Specifies the program to use for recording log messages during commit. If not set, the En1ToR 
environment variable is used instead. If en1Tor isnot set either, the default is /usr/ucb/vi. 


If this variable is set, then cvs will ignore all references to remote repositories in the cvs/Root 
file. 
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CVS_RSH 
CVS_SERVER 


CVSWRAPPERS 


AUTHORS 


Dick Grune 
Brian Berliner 


Jeff Polk 


SEE ALSO 


cvs uses the contents of this variable to determine the name of the ranote shall command to use 
when starting a cvs server. If this variable is not set then rsh is used. 

evs uses the contents of this variable to determine the name of the cvs server command. If this 
variable is not set then cvs is used. 

This variable is used by the cvswrappers script to determine the name of the wrappe file, in 


addition to the wrappers defaults contained in the repository (cvsrRooT/cvswrappers) and the 
user's home directory (~/.cvswrappers). 


Original author of the cvs she11 script version posted to comp. sources. unix in the volume 6 
release of D ecember, 1986. Credited with much of the cvs conflict resolution algorithms. 
Coder and designer of the cvs program itself in April, 1989, based on the original work done by 
Dick. 

H elped Brian with the design of the cvs module and vendor branch support and author of the 
checkin(1) shell script (the ancestor of cvs import). 


ci(1), co(1), cvs(5), cvsbug(8), dift(1), grep(1), patch(1), res(1), resditt(1), resmerge(1), rlogbug(8) 
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date— Show and set date and time 


SYNOPSIS 


date [ -u ][-c ][-n ][-d dsttype ] [ -t minutes-west ] [ -a [+\-]sss. fff ][+format ][ 
[yyyy Jmmddhhmmtyy }[.ss]] 


DESCRIPTION 


D ate without arguments writes the date and time to the standard output in the form: 


Wed Mar 8 14:54:40 EST 1989 


with est replaced by the local time zone’s abbreviation (or by the abbreviation for the time zone specified in thetz environ- 
ment variable if set). The exact output format depends on the locale. 


If acommand-line argument starts with a plus sign (+), the rest of the argument is used as a format that controls what 
appears in the output. In the format, when a percent sign (%) appears, it and the character after it arenot output, but rather 
identify part of the date or time to be output in a particular way (or identify a special character to output): 





Argument Sample output Explanation 

%a Wed Abbreviated weekday name* 

% Wednesday Full weekday name* 

%b Mar Abbreviated month name* 

%B March Full month name* 

%C Wed Mar @8 14:54:40 1989 D ate and time* 

%C 19 Century 

%d 08 D ay of month (always two digits) 
%D 03/08/89 M onth/day/year (eight characters) 


date 
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Argument Sample output Explanation 

%e 8 D ay of month (leading zero blanked) 

sh Mar Abbreviated month name* 

%H 14 24-hour-clock hour (two digits) 

%1 02 12-hour-clock hour (two digits) 

%j 067 Julian day number (three digits) 

%k 2 12-hour-clock hour (leading zero blanked) 
%1 14 24-hour-clock hour (leading zero blanked) 
am 03 M onth number (two digits) 

a] 54 M inute (two digits) 

en nn N ewline character 

sp) PM AM/PM designation 

%r 02:54:40 PM H our:minutesecond AM/PM designation 
%R 14:54 H our:minute 

%S 40 Second (two digits) 

%t nt T ab character 

%T 14:54:40 H our:minutesecond 

%U 10 Sunday-based week number (two digits) 
Saw 3 D ay number (one digit, Sunday is 0) 

aN 10 M onday-based week number (two digits) 
%X 03/08/89 D ate* 

%X 14:54:40 Time* 

sy 89 Last two digits of year 

%Y 1989 Year in full 

%Z EST Time zone abbreviation 

%+ Wed Mar 8 14:54:40 Est 1989 ~—— Default output format* 


* The exact output depends on the locale. 


If a character other than one of those shown in the preceding table appears after a percent sign in the format, that following 
character is output. All other characters in the format are copied unchanged to the output; a newline character is always 
added at the end of the output. 


In Sunday-based week numbering, the first Sunday of the year begins week 1; days preceding it are part of week 0. In 
M onday-based week numbering, the first M onday of the year begins week 1. 


To set thedate usea command-line argument with one of the following forms: 


1454 24-hour-clock hours (first two digits) and minutes 

081454 M onth day (first two digits), hours, and minutes 

03081454 M onth (two digits, January is 01), month day, hours, minutes 

8903081454 Year, month, month day, hours, minutes 

0308145489 Month, month day, hours, minutes, year (on System V-compatible systems) 
030814541989 Month, month day, hours, minutes, four-digit year 


198903081454 Four-digit year, month, month day, hours, minutes 
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If the century, year, month, or month day is not given, the current value is used. Any of the preceding forms may be 
followed by a period and two digits that give the seconds part of the new time if no seconds are given, zero is assumed. 


T hese options are available: 


-u OF -c Use GMT when setting and showing the date and time 

-n Do not notify other networked systems of the time change. 

-d dsttype Se the kernd-stored D aylight Saving Time type to the given value. (The kernd-stored D ST typeis 
used mostly by “old” binaries.) 

-t minutes-west Se the kerna-stored “minutes west of GMT” value to the onegiven on the command line (The 
kernd-stored DST typeis used mostly by “old” binaries.) 

-a adjustment Change the time forward (or backward) by the number of seconds (and fractions thereof) specified 


in the adjustment argument. Either the seconds part or the fractions part of the argument (but not 
both) may be omitted. On BSD -based systems, the adjustment is made by changing the rate at 
which time advances; on System-V - based systems, the adjustment is made by changing the time. 


FILES 
/usr/lib/locale/L/LC TIME Description of time locale L 
/usr/local/etc/zoneinfo Timezone information directory 


/usr/local/etc/zoneinfo/localtime Local time zone file 
/usr/local/etc/zoneinfo/posixrules Used with POSIX-styleTZs 
/usr/local/etc/zoneinfo/G M T For UTC leap seconds 


If /usr/local/etc/zoneinfo/GmT is absent, UTC leap seconds are loaded from /usr/1local/etc/zoneinfo/posixrules. 


dd 


dd— Convert a file while copying it (data dumper) 


SYNOPSIS 


dd [—help] [—version] [if=file] [of=file] [ibs=bytes] [obs=bytes] [bs=bytes ] 
[cbs=bytes] [skip=bl ocks ] [Seek=bl ocks ] [count=bl ocks] [conv={ascii, 
ebcdic, ibm, block, unblock, lcase, ucase, swab, noerror, notrunc, sync}] 


DESCRIPTION 


This manual page documents the GN U version of da. dd copies a file (from the standard input to the standard output, by 
default) with a user-selectable blocksize, while optionally performing conversions on it. 


OPTIONS 
Numbers can be followed by a multiplier: 
b=512, c=1, k=1024, w=2, xm=number m 


T hese options are available: 


—help Print a usage message on standard output and exit successfully. 

—version Print version information on standard output then exit successfully. 

if=file Read from file instead of the standard input. 

of=file W rite to file instead of the standard output. U nless conv=notrunc is given, truncate 
file to the size specified by seek= (0 bytes if seek= is not given). 

ibs=bytes Read bytes bytes at atime 

obs=bytes Writebytes bytes at atime. 


bs=byt es Read and writebytes bytes at atime. Override ibs and obs. 


depmod, modprobe 


cbs=bytes Convert bytes bytes at atime 

skip=bl ocks Skip bl ocks ibs-sized blocks at start of input. 

seek=bl ocks Skip bl ocks obs-sized blocks at start of output. 

count=b! ocks Copy only b! ocks ibs-sized input blocks. 

conv=conversion[,conversion...] Convert the file as specified by the conversion arguments. 

Conversions: 

ascii Convet EBCDIC to ASCII. 

ebcdic Convet ASCII to EBCDIC. 

ibm Convert ASCII to altanateEBCDIC. 

block Pad newlineterminated records to size of cbs, replacing newline with trailing spaces. 
unblock Replace trailing spaces in cbs-sized block with newline. 

lease Change uppercase characters to lowercase. 

ucase Change lowercase characters to uppercase. 

swab Swap every pair of input bytes. Unlike the UNIX aa, this works when an odd 


number of bytes are read. If the input file contains an odd number of bytes, the last 
byte is simply copied (since thereis nothing to swap it with). 


noerror Continue after read errors. 
notrunc Do not truncate the output file 
sync Pad every input block to size of ibs with trailing NuLLs. 
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depmod, modprobe 


depmod, modprobe— H andle loadable modules automatically 


SYNOPSIS 


depmod [-a] 
depmod modulel.o module2.o... 


modprobe module.o [symbol=value ...] 

modprobe -t tag pattern 

modprobe -a -t tag pattern modprobe -1 [ -t tag ] pattern 
modprobe -r module 

modprobe -c 


DESCRIPTION 


T hese utilities are intended to make a Linux modular kernel manageable for all users, administrators, and distribution 
maintainers. 


depmod creates a makefile-like dependency file based on the symbols it findsin the set of modules mentioned on the 
command line (or in a default place). This dependency file can later be used by modprobe to automatically load the relevant 
modules). 


modprobe is used to load a set of modules— either a single module, a stack of dependent modules, or all modules that are 
marked with a specified tag. 


modprobe will automatically load all base modules needed in a module stack, as described by the dependency file modules.dep. 
If the loading of one of these modules fails, the whole current stack of modules will be unloaded (by rmmod) automatically. 


modprobe has two ways of loading modules. O ne way (the probe mode) will try to load a module out of a list (defined by 
pattern). It stops loading as soon as one module load successfully. This can be used to autoload one Ethernet driver out of a 
list, for example. The other way is to load all modules from a list. T his can be used to load some modules at boot time 
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With the option -r, modprobe will automatically unload a stack of modules, similar to the way rmmod -r does. 


Option -1 combined with option -+ lists all available modules of a certain type An enhanced mount command could use the 
command: 


modprobe -1 -t fs 


to get the list of all file systan drivers available and on request load the proper one. So, the mount command could become 
more generic as well. (T he kerneld solves this without changing the mount utility.) 


Option -c will print all configuration (default + configuration file). 


Thenormal use of depmod isto includethe line /sbin/depmod -ain oneof therc-files in /etc/rc.d, So that the correct 
module dependencies will be available immediately after booting the system. 


Option -d puts depmod in debug mode. It outputs all commands it is issuing. 


Option -e outputs the list of unresolved symbol for each module, N ormally, depmod only outputs the list of unloadable 
modules. 


Option -v outputs the list of all processed modules. 


M odules may be located at different place in the filesystem, but there will always be some need to override this, especially for 
module devdopers. W e expect some official standard will emerge, defined by the FSSTN D. Until that time you might as 
wal use this suggested directory structure 


CONFIGURATION 


The behavior of depmod and modprobe can be adjusted by the (optional) configuration file /etc/conf.modules. 





The configuration file consists of a set of lines. All empty lines, and all text on aline after az, will be ignored. Lines may be 
continued by ending the line with a\. The remaining lines should all conform to one of the following formats: 


keep 

parameter=value 

options module symbol=value ... 
alias module real_name 
pre-install module command ... 
install module command ... 
post-install module command ... 
pre-remove module command ... 
remove module command ... 
post-remove module command ... 
parameter=value options module symbol=value ... alias module real_name 


All values in the parameter lines will be processed by a shdl, which means that shell tricks like wildcards and commands 
enclosed in backquotes can be used: 


path[misc]=/lib/modules/1.1.5?/misc 
path[net]=/lib/modules/'uname -r'/net 
Parameters may be repeated multiple times. 
T hese are the legal parameters: 


depfile=DEPFILE PATH Thisisthepath to the dependency file that will be created by depmod and used by modprobe. 

path=SOME_PATH The path parameter specifies a directory to search for the modules. 

path[tag]=SOME_PATH The path parameter can carry an optional tag. T his tells us a little more about the purpose of the 
modules in this directory and allows some automated operations by modprobe. T he tag is appended 
to the path keyword enclosed in square brackets. If the tag is missing, the tag misc is assumed. O ne 
very useful tag iS boot, which can be used to mark all modules that should be loaded at boot time 


If the configuration file /etc/conf.modules iS missing, or if any parameter is not overridden, the following defaults are 
assumed: 


depmod, modprobe = | 


depfile=/lib/modules/'uname -r'/modules.dep 
path[boot]=/1ib/modules/boot 


path[fs]=/lib/modules/'uname -r'/fs 
path[misc]=/lib/modules/'uname -r'/misc 
path[net]=/lib/modules/'uname -r'/net 
path[scsi]=/lib/modules/'uname -r'/scsi 


path[fs]=/lib/modules/default/fs 
path[misc]=/lib/modules/default/misc 
path[net]=/lib/modules/default/net 
path[scsi]=/lib/modules/default/scsi 


path[fs]=/lib/modules/fs 
path[misc]=/lib/modules/misc 
path[net]=/1ib/modules/net 
path[scsi]=/lib/modules/scsi 














All option lines specify the default options that are needed for amodule, asin 

modprobe de62@ bnc=1 

T hese options will be overridden by any options given on the modprobe command line. 

Thealias lines can be used to give alias names to modules. A linein /etc/conf.modules that looks like this: 


alias iso9660 isofs 


makes it possible to write modprobe isog966a, although thereis no such module available. 


STRATEGY 


The idea is that modprobe will look first at the directory containing modules compiled for the current release of the kernd.. If 
the module is not found there, modprobe will look in the directory containing modules for a default release. 


W hen you install anew Linux, the modules should be moved to a directory rdated to the release (and version) of thekernd 
you are installing. Then you should do a symlink from this directory to the default directory. 





Each time you compile a new kernel, the command make modules_instal1 will create anew directory, but won't change the 
default. 


When you gét a module unrelated to the kernel distribution, you should place it in one of the version-independent 
directories under /1ib/modules. 


This is the default strategy, which can be overridden in /etc/conf.modules. 


EXAMPLES 
modprobe -t net Load one of the modules that are stored in the directory tagged net. Each module is tried until one 
succeeds. (D efault: /1ib/modules/net). 


modprobe -a -t boot All modules that are stored in the directory tagged boot will be loaded. (D efault: /1ib/modules/ 
boot). 


modprobe slip.o This will attenpt to load the module sinc.o if it was not previously loaded, since the sip module 
needs the functionality in the sinc module. This dependency will be described in the file 
modules.dep that was created automatically by depmod. 


modprobe -r slip.o Will unload siip.o. It will also unload sihc.o automatically, unless it is used by some other module 
as well (such as ppp.o). 


FILES 
/etc/conf.modules 
/1ib/modules/*/modules.dep 
/lib/modules /* 
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SEE ALSO 


1smod(1), kerneld(8), ksyms(1), modules(2) 


REQUIRED UTILITIES 


insmod(1), nm(1) rmmod(1) 


NOTES 


The pattern supplied to modprobe will often be escaped to ensure that it is evaluated in the proper context. 


AUTHOR 


Jacques G elinas (jack@solucorp.qc.ca), Bjorn Ekwall (bjarn@blox.se) 


BUGS 
N aah... 
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df— Summarize free disk space 


SYNOPSIS 
df [-aikPv] [-t fstype] [-x fstype] [—all] [—inodes] [—type=fstype] 
[—exclude-type=fstype] [—kilobytes] [—portability] [—print-type] 
[—help] [—version] [filename...] 

DESCRIPTION 


This manual page documents the GN U version of df. at displays the amount of disk space available on the filesystem 
containing each filename argument. If no filename is given, the space available on all currently mounted filesystems is shown. 
Disk space is shown in 1K blocks by default, unless the environment variable postxLy_corrEcT is set, in which case 512-byte 
blocks are used. 


If an argument is the absolute filename of a disk device node containing a mounted filesystem, df shows the space available 
on that filesystem rather than on the filesystem containing the device node (which is always the root filesystem). T his version 
of af cannot show the space available on unmounted filesystems, because on most kinds of systems doing so requires very 
nonportable, intimate knowledge of filesystem structures. 


OPTIONS 


-a, —all Include in the listing filesystems that have 0 blocks, which are omitted by default. Such 
filesystems are typically special-purpose pseudo-filesystems, such as automounter entries. On 
some systems, filesystems of type ignore or auto are also omitted by default and included in the 
listing by this option. 

-i, —inodes List inode usage information instead of block usage An inode (short for “index node’) isa 
special kind of disk block that contains information about a file such asits owner, permissions, 
timestamps, and location on the disk. 





-k, —kilobytes Print sizesin 1K blocks instead of 512-byte blocks. This overrides the environment variable 
POSIXLY_CORRECT. 
-P, —portability Use the posrx output format. T his is like the default format except that the information about 


each filesysten is always printed on exactly oneline; amount deviceis never put on alineby 
itself. This means that if the mount device name is more than 20 characters long (as for some 
network mounts), the columns are misaligned. 


oi 


-T, —print-type Print a type string for each filesystem. Any such printed filesystan type name may be used as an 
argument to either of the —type= or —exclude-type= options. 
-t, —type=fstype Limit the listing to filesystems of type fst ype. M ultiple filesystem types can be shown by giving 


multiple -t options. By default, all filesystem types are listed. 


-x, —exclude-type=fstype | Limit thelisting to filesystems not of type fstype. M ultiple filesystem types can be diminated by 
giving multiple -x options. By default, all filesystem types are listed. 


-V Ignored; for compatibility with System V versions of df. 
—help Print a usage message on standard output and exit successfully. 
—version Print version information on standard output then exit successfully. 
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dig 
dig— Send domain name query packets to name servers 


SYNOPSIS 


dig [@server] domain [<query-type>][<query-class>][+<query-option>][-<di g-option>] 
[%c omment ] 
DESCRIPTION 


dig (domain information groper) is a flexible command-line tool that can be used to gather information from the D omain 
N ame System servers. dig has two modes: simple interactive mode that makes a single query, and batch that executes a query 
for each in alist of several query lines. All query options are accessible from the command line. 


The usual simple use of dig takes the form: 
dig @server domain query-type query-class 
whee 


server M ay be athe: a domain name or adot-notation Internet address. If this optional fidd is omitted, 
dig will attempt to use the default name server for your machine 





NOTE 


If adomain nameis specified, this will be resolved using the domain name system resolver (BIND). If your system doesnot 
support DNS, you may have to specify a dot-notation address. Alternatively, if there is a server at your disposal some 
where, all that is required isthat /etc/resolv.conf be present and indicate where the default name servers reside, so that 
server itself can be resolved. See resolver(5) for information on /etc/resolv.conf. 


Changing /etc/resolv.conf will affect the standard resolver library and potentially several programs that use it.) As an 
option, theuser may set theenvironment variable LocaLres to namea file which is to be used instead of /etc/resolv.conf 
(LOCALRES is specific to the dig resolver and not referenced by the standard resolver). If the LocaLres variable is not set or 
the file is not readable, then /etc/resolv.conf will be used. 


domain The domain name for which you are requesting information. See “O ptions” [ -x] for a convenient 
way to specify inverse address query. 
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query-type The type of information (DN S query type) that you are requesting. If omitted, the default isa (T_a 
= address). T he following types are recognized: 





T ype Example D exription 
a TA N etwork address 
any T_ANY All/any information about specified domain 
mx T_MX M ail exchanger for the domain 
ns T_NS N ame servers 
soa T_SOA Zone of authority record 
hinfo T_HINFO H ost information 
axfr T_AXFR Zone transfer (must ask an authoritative server) 
txt T_TXT Arbitrary number of strings 
(See RFC 1035 for the complete list. ) 
query-class The network class requested in the query. If omitted, the default is in (c_IN = Internet). The 
following classes are recognized: 
in C_IN Internet class domain 
any C_ANY All/any class information 


(See RFC 1035 for the complete list. ) 


NOTE 


any can be used to specify a class and/or a type of query. dig will parse the first occurrence of any to mean query-type = 


T_ANY. 
To specify query-class = C_ANY you must either specify any twice, or set query-class using -c option. (See “O ther O p- 
tions,” next.) 
OTHER OPTIONS 
%ignored-comment % iS used to include an argument that is simply not parsed. This may be useful if running dig in 
batch mode. Instead of resolving every @server-domain- name in alist of queries, you can avoid the 
overhead of doing so, and still have the domain name on the command line as a reference. 
Example: 
dig @128.9.0.32 %venera.isi.edu mx isi.edu 

-<dig option> - is used to specify an option that affects the operation of dig. T he following options are currently 


available (although not guaranteed to be useful): 

-x dot-notation-address | Convenient form to specify inverse address mapping. Instead of 
dig 32.0.9.128.in-addr.arpa 
onecan simply use 
dig -x 128.9.0.32 

-f file File for dig batch mode. The file contains a list of query 
specifications (dig command lines) which are to be executed 
successively. Lines beginning with ;, #, or \n areignored. Other 
options may still appear on the command line, and will bein 
effect for each batch query. 

-T time Time in seconds between start of successive queries when running 
in batch mode Can be used to keep two or more batch dig 
commandsrunning roughly in sync. D efault is zero. 


-envsav 


dig 115 


-p port Port number. Query aname server listening to anonstandard port 
number. D efault is 53. 
-P[ping-string] After query returns, execute a ping(8) command for response time 


comparison. T his rather unelegantly makes a call to the shell. The 
last three lines of statistics is printed for the command: 
ping -sserver_name 56 3 
If the optional ping string ispresent, it replaces ping -sin the 
shell command. 
-t query-type Specify type of query. M ay specify either an integer value to be 
included in the type field or use the abbreviated mnemonic as 
discussed earlier (mx = T_Mx). 
-c query-Class Specify class of query. M ay specify either an integer value to be 
included in the class field or use the abbreviated mnemonic as 
discussed earlier (in = C_IN). 
This flag specifies that the dig environment (defaults, print options, and so on), after all of the 
arguments are parsed, should be saved to a file to become the default environment. U seful if you do 
not like the standard set of defaults and do not desire to include a large number of options each 
time dig is used. The environment consists of resolver state variable flags, timeout, and retries as 
well as the flags detailing dig output (see below). If the shall environment variable LocaLpeF is set to 
thename of afile, this is where the default aig environment is saved. If not, thefile pic. env is 
created in the current working directory. 








NOTE 


LOCALDEF iS specific to the dig resolver, and will not affect operation of the standard resolver library. 


-envset 


-[no]stick 


+<query option> 


Keyword Abbreviation 


Each time dig is executed, it looks for . /Dic.env or the file specified by the shel environment 
variable LocaLoer. If such file exists and is readable, then the environment is restored from this file 
before any arguments are parsed. 

This flag only affects batch query runs. When -envset is specified on alinein adig batch file, the 
dig environment after the arguments are parsed, becomes the default environment for the duration 
of the batch file, or until the next line which specifies -envset. 

This flag only affects batch query runs. It specifies that the dig environment (as read initially or set 
by -envset switch) is to be restored before each query (line) in a dig batch file T he default -nostick 
means that the dig environment does not stick, hence options specified on asinglelinein adig 
batch file will remain in effect for subsequent lines (that is, they are not restored to the sticky 
default). 

+ iS used to specify an option to be changed in the query packet or to change dig output specifics. 
M any of these are the same parameters accepted by nslookup(8). If an option requires a parameter, 
the form is as follows: 

tkeyword[=value] 


M ost keywords can be abbreviated. Parsing of the + optionsis very simplistic— a value must not be 
separated from its keyword by whitespace. T he following keywords are currently available: 


M eaning (D efault) 





[no]debug (deb) 
[no]d2 
[no]recurse (rec) 


retry=# (ret) 


Turn on/off debugging mode [deb] 

Turn on/off extra debugging mode [noa2] 
Use/don’t use recursive lookup [rec] 

Se& number of retries to #[4] 


continues 
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Keword Abbreviation M eaning (D efault) 

time=# (ti) Se timeout length to # seconds [4] 
[no]ko Keep open option (implies vc) [noko] 
[no]vc Use/don’t use virtual circuit [nove] 


[no]defname (def) 
[no] search (sea) 
domain=NAME (do) 
[no]ignore (i) 
[no]primary (pr) 
[no]aaonly (aa) 
[no]sort (sor) 
[no]cmd 
[no]stats (st) 
[no]Header (H) 
[no] header (he) 
[no]ttlid (tt) 
[no]cl 

[no]qr 
[no]reply (rep) 
[no]ques (qu) 
[no]answer (an) 
[no]author (au) 
[no]addit (ad) 
def 





min 
set=# 
and=# 





Pp 
Pp 
Pp 
Pp 
pfor=# 
T 
a 


August 30, 1990 


for i = @ to retry - 1 

for j = 1 to num_servers 
send_query 

wait((time * (2**i)) / num_servers) 
end 

end 


Use/don’t use default domain name [def] 
Use/don’t use domain search list [sea] 
Se default domain name to NAME 
Ignore/don’t ignoretrunc. errors [noi] 
Use/don’t use primary server [nopr] 
Authoritative query only flag [noaa] 
Sort resource records [nosor] 

Echo parsed arguments [ cma] 

Print query statistics [st] 

Print basic header [] 

Print header flags [he] 

Print TT Ls[tt] 

Print class info [noc1] 

Print outgoing query [nogr] 

Print reply [rep] 

Print question section [qu] 

Print answer section [an] 

Print authoritative section [au] 

Print additional section [aa] 

Se to default print flags 

Set to minimal default print flags 

Set print flags to # (# can be hex/octal/decimal) 
Bitwise and print flags with # 

Bitwise or print flags with # 





he€ retry and time options affect the reransmission strategy used by resolver library when sending datagram queries. The 
gorithm is as follows: 


N ote that dig always uses a value of 1 for num_servers. 


DETAILS 


dig once required a slightly modified version of the Brnp resolver (3) library. B1ND’s resolver has (as of B1nD 4.9) been 


augmented to work properly with dig. Essentially, dig is a straightforward (albeit not pretty) effort of parsing arguments and 
setting appropriate parameters. dig uses resolver routinesres_init(), res_mkquery(), res_send() aS Wal as accessing res 
structure. 
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FILES 


/etc/resolv.conf Initial domain name and name server addresses 


ENVIRONMENT 
LocaLres file to use in place of /etc/resolv.conf 


LOCALDEF default environment file 


AUTHOR 


Steve H otz (hotz@isi.edu) 


ACKNOWLEDGMENTS 


dig uses functions from nslookup(8) authored by Andrew Cherenson. 


BUGS 


dig has a serious case of “creeping featurism,” the result of considering several potential uses during its devdopment. It would 
probably benefit from a rigorous diet. Similarly, the print flags and granularity of the items they specify make evident their 
rather ad hoc genesis. 


dig does not consistently exit nicely (with appropriate status) when a problem occurs somewhere in the resolver (M ost of the 
common exit cases are handled.) T his is particularly annoying when running in batch mode. If it exits abnormally (and is not 
caught), the entire batch aborts; when such an event is trapped, dig simply continues with the next query. 


SEE ALSO 


named(8), resolver(3), resolver(5), nslookup(8) 
30 August 1990 


dnsquery 


dnsquery—Query domain name servers using resolver 


SYNOPSIS 
dnsquery [-n nameserver] [-t type] [-c class] [-r retry] [-p retry period] 
[-d] [-s] [-v] host 

DESCRIPTION 


The dnsquery program is a general interface to nameservers via BIND resolver library calls. The program supports queries to the 
nameserver with an opcode of query. This program is intended to be a replacement or supplement to programs like nstest, 
nsquery, and nslookup. All arguments except for host and ns are treated without case-sensitivity. 


OPTIONS 
-n The nameserver to be used in the query. N ameservers can appear as either Internet addresses of the form 
w.x.y.z OF Can appear as domain names. (default: as specified in /etc/resolv.conf) 

-t The type of resource record of interest. T ypes include: 
A Address 
NS N ameserver 
CNAME Canonical name 
PTR Domain name pointer 


SOA Start of authority 
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WKS W ell-known service 
HINFO H ost information 
MINFO M ailbox information 
MX M ail exchange 

RP Responsible person 
MG Mail group menber 
AFSDB DCE or AFS serve 
ANY Wildcard 


NOTE 


Any case may be used (the default is any) 


-c The class of resource records of interest. C lasses include the following: 
IN Internet 
HS H esiod 
CHAOS Chaos 
ANY Wildcard 


NOTE 


Any case may be used (the default is 1n). 


r Thenumber of times to retry if the nameserver is not responding. (default: 4) 
-p Period to wait before timing out. (default: Res_TIMEOUT) options fidd. (default: any answer) 
-d Turn on debugging. T his sets the res_pesue bit of the resolver’s options field. (default: no debugging) 
-s Use astream rather than a packet. T his uses aT CP stream connection with the nameserver rather than a 
UDP datagram. T his sets the res_useve bit of the resolver’s options field. (default: upp) 
-V Synonym for the s flag. 
host The name of the host (or domain) of interest. 
FILES 
Jetc/resolv.conf To get the default ns and search lists. 
<arpa/nameser .h> List of usable rr types and classes 
<resolv.h> List of resolver flags 
SEE ALSO 
nslookup(8), nstest(1), nsquery(1), named(8), resolver(5) 
DIAGNOSTICS 


If the resolver fails to answer the query and debugging has not been turned on, dnsquery will simply print a message like this: 


Query failed (rc = 1) : Unknown host 


The value of the return code is supplied by h_errno. 


deplit 
BUGS 


Queries of aclass other than 1n can have interesting results since ordinarily a nameserver only has a list of root nameservers 
for class In resource records. 


Query usesa Call to inet_addr() to determine if the argument for the -n option isa valid Internet address. U nfortunatdy, 
inet_addr() seams to cause a segmentation fault with some (bad) addresses (for example, 1.2.3.4.5). 


AUTHOR 

Bryan Beecher 

10 M arch 1990 

domainname 

domainname— Set or print domain of current host 
SYNOPSIS 

domainname [ name ] 
DESCRIPTION 


domainname prints the domain name of the current host, from the getdomainname(3) library call. If an argument is present and 
the effective UID iso, domainname changes the name of the host, with the setdomainname(2) system call. Thisis usually done at 
boot timein the /etc/rc.1ocal script. 


FILES 


/etc/rc.local 


SEE ALSO 


getdomainname(3), setdomainname(2), uname(1), uname(2) 


AUTHOR 


Lars Wirzenius by substituting in hostname.c 
Linux 0.98, 26 December 1992 


dsplit 


dsplit— Split a large file into pieces 


SYNOPSIS 
dsplit [ -size nnn ][input_file [ output_base ]] 
DESCRIPTION 
dsplit Splits binary filesinto smaller chunks so that they may be placed on floppy disks. 
OPTIONS 
-size nnn Specifies the size of each output file, in bytes. The default is 1457000, which is nough to will a 
1.44M B floppy disk. 
input_file Specifies the name of the file to split up. A - indicates standard input. T he default is standard 


input. 
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output_base Specifies the name of the output files to be written. dsp1it will append eo, 001, ..., to the 
output_base. | he default is dsplit. 


AUTHOR'S NOTES 
Submitted by: D avid Arnstein (arnstein@netcom.com) 
Posting number: Volume 40, Issue 51 
Archivename: dsplit/partot 
Environment: MS-DOS, UNIX 
H ereisa portable binary file splitting program. It reads a binary file and splits it into pieces. | use this program to put large 


binary files on floppy disks. For this reason, the default size of the output files is 1,457,000 bytes, which just about fillsup a 
1.44M B floppy disk. 


Unlike other binary split programs! have seen, dsp1it does not malloc ahuge block of memory. dsplit is suitable for use 
under M S-D OS and other primitive operating systems. 


(The program camefrom gatekeeper.dec.com: /pub/usenet/comp.sources.misc/volume40/dsplit). 
Linux 1.1, 5 July1994 


du 


du— Summarize disk usage 


SYNOPSIS 


du [-abcklsxDLS] [—all] [—total] [—count-links] [—summarize] [—bytes] 
[—kilobytes] [—one-file-system] [—separate-dirs] [—dereference] 
[—dereference-args] [—help] [—-version] [filename...] 


DESCRIPTION 


This manual page documents the GN U version of du. du displays the amount of disk space used by each argument and for 
each subdirectory of directory arguments. T he space is measured in 1K blocks by default, unless the environment variable 
POSIXLY_CORRECT is set, in which case 512-byte blocks are used. 














OPTIONS 

-a, —all Display counts for all files, not just directories. 

-b, —bytes Print sizes in bytes. 

-c, —tota W rite a grand total of all of the arguments after all arguments have bem processed. This can 
be used to find out the disk usage of a directory, with some files excluded. 

-k, —kilobytes Print sizes in kilobytes. T his overrides the environment variable posrxLY_CoRRECT. 

-1, —count -links Count the size of all files, even if they have appeared already in another hard link. 

-s, —summarize Display only atotal for each argument. 

-x, —one-file-system Skip directories that are on different filesystems from the one that the argument bang 
processed is on. 

-D, —dereference-args D ereference symbolic links that are command-line arguments. D oes not affect other 
symbolic links. Thisis hdpful for finding out the disk usage of directories like /usr/tmp 
where they are symbolic links. 

-L, —dereference D ereference symbolic links (show the disk space used by the file or directory that the link 
points to instead of the space used by the link). 

-S, —separate-dirs Count the size of each directory separatdy, not including the sizes of subdirectories. 

—help Print a usage message on standard output and exit successfully. 


—version Print version information on standard output, then exit successfully. 


editres [= | 
BUGS 


On BSD systems, du reports sizes that are half the correct values for files that are N FS-mounted from H P-U X systems. On 
HP-UX systems, it reports sizes that are twice the correct values for files that are N FS-mounted from BSD systens. Thisis 
due to a flaw in HP-UX; it also affects the H P-UX au program. 


GNU FileUtilities 
editres 
editres— A dynamic resource editor for X T oolkit applications 
SYNTAX 
editres [ -toolkitoption ... ] 
OPTIONS 


editres accepts all of the standard X Toolkit command-line options (seex(1)). The order of the command-line options is not 
important. 


DESCRIPTION 


editres iSatool that allows users and application developers to view the full widget hierarchy of any X Toolkit application 
that speaks the editres protocol. In addition, editres will hdp the user construct resource specifications, allow the user to 
apply the resource to the application and view the results dynamically. O nce the user is happy with a resource specification, 
editres will append the resource string to the user’s X Resources file. 


USING editres 


editres provides a window consisting of the following four areas: 


M enu Bar A set of pop-up menus that allow you full access to editres’s features. 
Panner The panner provides a more intuitive way to scroll the application tree display. 
M essage Area Displays information to the user about the action that editres expects. 


Application Widget Tree This area is used to display the selected application’s widget tree. 


To begin an editres session, sdect the Ge Widget Tree manu iten from the Command menu. This will change the pointer 
cursor to crosshair. You should now sdect the application you wish look at by clicking on any of its windows. If this 
application understands the editres protocol, editres will display the application's widget tree in its tree window. If the 
application does not understand the editres protocol, editres will inform you of this fact in the message area after a few 
seconds delay. 


After you havea widget tree, you may select any of the other menu options. T he effect of each of these is described in 
“Commands,” next. 


COMMANDS 


Get Widget T ree Allows the user to click on any application that speaks the editres protocol and receive its 
widget tree 

Refresh Current Widget Tree editres only knows about the widgets that exist at the present time M any applications 
create and destroy widgets on the fly. Sdecting this menu item will cause editres to ask the 
application to resend its widget tree, thus updating its information to the new state of the 
application. 
For example, xman only creates the widgets for its topbox when it starts up. N one of the 
widgets for the manual page window are created until the user actually clicks on the M anual 
Page button. If you retrieved xman’s widget tree before the manual page is active, you may 
wish to refresh the widget tree after the manual page has been displayed. T his will allow you 
to also edit the manual page's resources. 
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Dump W idget Tree to aFile 


Show Resource Box 


Se Resource 


Quit 
TREE COMMANDS 


W hen documenting applications it is often useful to be able to dump the entire application 
widget tree to an ASCII file. This file can then be included in the manual page. W hen this 
menu item is selected, a pop-up dialog is activated. T ype the name of the file in this dialog, 
and either sdect O kay, or type a carriagereturn. editres will dump the widget tree to this 
file. To cancel the file dialog, select the Cancel button. 

This command will pop up a resource box for the current application. T his resource box 
(described in detail later in this section) will allow the user to see exactly which resources 
can be set for the widget that is currently sdected in the widget tree display. Only one 
widget may be currently selected; if greater or fewer are sdected, editres will refuse to pop 
up the resource box and put an error message in the M essage A rea. 


This command will pop up asimple dialog box for setting an arbitrary resource on all 
selected widgets. You must type in the resource name, as wd as the value. You can usethe 
T ab key to switch between the resource name field and the resource value field. 


Exits editres. 


The T ree menu contains several commands that enable operations to be performed on the widget tree. 


Sdect Widget in Client 


Sdect All, Unselect All, 
Invert All 

Select Children, 

Select Parents 

Select D escendants, 
Select Ancestors 

Show W idget N ames, 
Show Class N ames, 
Show W idget Windows 


Flash Active Widgets 


This menu item allows you to select any widget in the application; editres will then 
highlight the corresponding element the widget tree display. After this menu item is 
selected, the pointer cursor will again turn to a crosshair, and you must click any pointer 
button in the widget you wish to have displayed. Since some widgets are fully obscured by 
their children, itis not possible to get to every widget this way, but this mechanism does 
give very useful feedback between the elements in the widget tree and thosein the actual 
application. 


T hese functions allow the user to sdect, unselect, or invert all widgets in the widget tree 


T hese functions select the immediate parent or children of each of the currently selected 
widgets. 

T hese functions select all parents or children of each of the currently selected widgets. This 
iS a recursive search. 

W hen the tree widget is initially displayed, thelabels of each widget in the tree correspond 
to the widget names. T hese functions will cause the labd of all widgets in the tree to be 
changed to show the class name, IDs, or window associated with each widget in the 
application. The widget ID s, and windows are shown as hex numbers. 

In addition, there are keyboard accelerators for each of the T ree operations. If the input 
focus is over an individual widget in the tree, then that operation will only affect that 
widget. If the input focus isin the T ree background, it will have exactly the same effect as 
the corresponding menu iten. 

The translation entries shown may be applied to any widget in the application. If that 
widget is a child of the T ree widget, then it will only affect that widget; otherwise it will 
have the same effect as the commands in the T ree menu. 

This command is the inverse of the Sdect Widget in Client commana; it will show the user 
each widget that is currently selected in the widget tree by flashing the corresponding widget 
in the application numFlashes (three by default) times in the flash-Color. 





Key Option Trangation Entry 
space Unselect Sdect(nothing) 

w Sdect Select(widget) 

S Select Sdect(all) 

i Invert Sedect(invert) 


editres 





Key Option Trangation Entry 

c Select Children Select(children) 
d Select D escendants Select( descendants) 

p Sdect Parent Sdect(parent) 

a Sdect Ancestors Sdect(ancestors) 

N Show W idget N ames Relabel(name) 

C Show Class N ames R elabel(class) 

| Show Widget IDs Relabel(id) 

Ww Show W idget Windows Relabel(window) 

T Toggle W idget/ClassName § Réelabd(toggle) 


Clicking button 1 on a widget adds it to the set of sdected widgets. Clicking button 2 on a widget desdects all other widgets 
and then selects just that widget. Clicking button 3 on awidget toggles its label between the widget’s instance name the 


widget’s class name. 


USING THE RESOURCE BO X 


T he resource box contains five different areas. Each of the areas, as they appear on the screen from top to bottom, are 


discussed in the following list: 
The Resource Line 


The Widget N ames and C lasses 


Normal and Constraint Resources 


Resource V alue 


This area at the top of the resource box shows the current resource name exactly as it 
would appear if you were to saveit to afile or apply it. 

This area enables you to select exactly which widgets this resource will apply to. The 
area contains four lines; the first contains the name of the selected widget and all its 
ancestors, and the more restrictive dot (.) separator. The second line contains less 
specific class names of each widget, as well as the less restrictive star (*) separator. 

The third line contains a set of special buttons called Any W idget that will generalize 
thislevel to match any widget. The last line contains a set of special buttons called 
Any Widget Chain that will turn the single level into something that matches zero or 
more levds. 

The initial state of this area is the most restrictive using the resource names and the 
dot separator. By selecting the other buttons in this area, you can ease the restrictions 
to allow more and more widgets to match the specification. The extreme case is to 
select all the Any Widget Chain buttons, which will match every widget in the 
application. As you select different buttons, the tree display will update to show you 
exactly which widgets will be affected by the current resource specification. 

Thenext area allows you to select the name of the normal or constraint resources 
you wish to set. Some widgets may not have constraint resources, so that area will 
not appear. 

This next area allows you to enter the resource value. T his value should be entered 
exactly as you would type a line into your resource file. T hus, it should contain no 
unescaped newlines. There are a few special character sequences for this file: 

\n- This will be replaced with a newline. 

\#H#- W here # is any octal digit. T his will be replaced with a single 
byte that contains this sequence interpreted as an octal 
number. For example, a value containing a NuLL byte can be 
stored by specifying \oo0. 

This will compress to nothing. 
\\- This will compress to a single backslash. 


\<new-line>- 
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Command Area This area contains several command buttons, described in the following list: 


The Set Save File button allows the user to modify file that the resources will be 
saved to. This button will bring up a dialog box that will ask you for a filerame 
after the filename has bem entered, either hit carriage return or click on the 
Okay button. To pop down the dialog box without changing the save file, click 
the Cancel button. 


The Save button will append the resource line already described to the end of the 
current save file. If no save file has been set, the Se Save File dialog box will be 
popped up to prompt theuser for a filename. 


TheApply button attempts to peform a xtsetvalues call on all widgets that 
match the resource line described earlier. T he value specified is applied directly 
to all matching widgets. This behavior is an attempt to give adynamic fed to the 
resource editor. Since this feature allows users to put an application in states it 
may not be willing to handle, a hook has been provided to allow specific 
applications to block these setvalues requests. (See “Blocking editres Requests,” 
following). 

Unfortunately, due to design constraints imposed on the widgets by the X 
Toolkit and the Resource M anager, trying to coerce an inherently static system 
into dynamic behavior can cause strange results. There is no guarantee that the 
results of an apply will be the same as what will happen when you save the value 
and restart the application. T his functionality is provided to try to give you a 
rough feel for what your changes will accomplish, and the results obtained 
should be considered suspect at best. H aving said that, this is one of the neatest 
features of editres, and | strongly suggest that you play with it, and see what it 
can do. 

The Save and Apply button combines the Save and Apply actions described 
earlier into one button. 

The Popdown Resource Box button will remove the resource box from the 
display. 





BLOCKING editres REQUESTS 


The editres protocol has been built into the Athena W idget set. T his allows all applications that are linked against xaw to be 
able to speak to the resource editor. Although this provides great flexibility, and is a useful tool, it can quite easily be abused. 
It istherefore possible for any xaw application to specify a value for the editresBlock resource to keep editres from divulging 
information about its internals, or to disable the setvalues part of the protocol. 

editresBlock (Class Editresblock) Specifies which type of blocking this application wishes to imposeon the editres protocol. 


The accepted values are as follows: 


all Block all requests. 

setValues Block all setvalues requests. As thisis the only editres request that actually modifies the application, this 
isin effect stating that the application is read-only. 

none Allow all editres requests. 


Remember that these resources are set on any xaw application, not editres. T hey allow individual applications to keep all or 
some of the requests editres makes from ever succeeding. Of course, editres is also an Xaw application, so it may also be 
viewed and modified by editres (rather recursive, | know); these commands can be blocked by setting the editresBlock 
resource on editres itself. 


RESOURCES 
For editres, the available application resources are as follows: 


numFlashes (Class NumFlashes) specifies the number of times the widgets in the application will be flashed when the Show 
Active W idgets command in invoked. 


editres 


flashTime (Class FlashTime) specifies the mount of time between the flashes described in the preceding entry. 


flashColor (Class flashColor) specifies the color used to flash application widgets. A bright color should be used that will 
immediately draw your attention to the area being flashed, such as red or ydlow. 


saveResourcesFile (Class SaveResourcesFile) is the file the resource line will be append to when the Save button activated in 
the resource box. 


WIDGETS 


In order to specify resources, it is useful to Know the hierarchy of the widgets that compose editres. In the following 
notation, indentation indicates hierarchical structure. T he widget class name is given first, followed by the widget instance 
name 


Editres editres 
Paned paned 
Box box 
MenuButton commands 
SimpleMenu menu 
SmeBSB sendTree 
SmeBSB refreshTree 
SmeBSB dumpTreeToFile 
SmeLine line SmeBSB getResourceList 
SmeLine line 
SmeBSB quit 
MenuButton treeCommands 
SimpleMenuumenu 
SmeBSB showClientWidget 
SmeBSB selectAll 
SmeBSB unselectAll 
SmeBSB invertAll 
SmeLine line 
SmeBSB selectChildren 
SmeBSB selectParent 
SmeBSB selectDescendants 
SmeBSB selectAncestors 
SmeLine line 
SmeBSB showWidgetNames 
SmeBSB showClassNames 
SmeBSB showWidgetIDs 
SmeBSB showidgetWindows 
SmeLine line 
SmeBSB flashActiveWidgets 
Paned hPane 
Panner panner 
Label userMessage 
Grip grip 
Porthole porthole 
Tree tree 
Toggle <name of widget in application> 


TransientShell resourceBox 
Paned pane 

Label resourceLabel 

Form namesAndClasses 
Toggle dot 

Toggle star 

Toggle any 

Toggle name 
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Toggle class 


Label namesLabel 
List namesList 

Label constraintLabel 
List constraintList 
Form valueForm 

Label valueLabel 
Text valueText 

Box commandBox 
Command setFile 
Command save 

Command apply 
Command saveAndApply 
Command cancel 





Grip grip 
Grip grip 

ENVIRONMENT 

DISPLAY To get the default host and display number 

XENVIRONMENT To ge@ the name of aresource file that overrides the global resources stored in the RESOURCE_MANAGER 

propety. 

FILES 

<XRoot>/1ib/X11/app-defaults/Editres specifies required resources. 
SEE ALSO 

x(1), xrdb(1), Athena Widget Set 
RESTRICTIONS 


Thisis a prototype T here are lots of nifty features! would loveto add, but | hope this will give you some ideas about what a 
resource editor can do. 


AUTHOR 
ChrisD. Peterson (formerly MIT X Consortium) 
X Version 11 Release 6 


elvis, ex, V1, View, input 
elvis, ex, vi, view, input— T he editor 


SYNOPSIS 


elvis [flags ][t+cmd][files...] 


DESCRIPTION 
elvis iS a text editor that emulates vi/ex. 


On systems which pass the program name as an argument, such as U NIX and M inix, you may also install elvis under the 
namé ex, vi, view, and input. T hese extra names would normally be links to elvis; see the 1n shell command. 


duis ex, vi, niew, input 127 


W hen elvis isinvoKed as vi, it behaves exactly as though it was invoked as elvis. H owever, if you invoke elvis as view, then 
the readonly option isset as though you had given it the -r flag. If you invoke elvis aSex, then elvis will start up in the 
colon Command mode instead of the visual command mode, asthough you had given it the -e flag. If you invoke elvis as 
input or edit, then elvis will start up in input mode, as though the -: flag was given. 


OPTIONS 


r 


-t tag 
-m [file] 


-e 
“Vv 
-i 
-w winsize 


+command OF -c command 


FILES 


/tmp/elv* 


tags 


-exrc Of elvis.rc 


ENVIRONMENT 


TERM 


TERMCAP 


TERMINFO 


LINES, COLUMNS 


EXINIT 


To the real vi, this flag means that a previous edit should be recovered. elvis, though, has a 
separate program, called elvrec(1), for recovering files. When you invoke elvis with -r, elvis will 
tell you to run elvrec. 


This sets the readonly option, so you won't accidentally overwrite a file 


This sets the safer option, which disables many potentially harmful commands. It has not ben 
rigorously proven to be absolutely secure, however. 


This causes elvis to start editing at the given tag. 


elvis will search through fi! e for something that looks like an error message from a compile. It 
will then begin editing the source file that caused the error, with the cursor sitting on the line where 
the error was detected. If you don’t explicitly namea file, then errlist is assumed. 


elvis will start up in colon command mode 
elvis will Start up in visual command mode 
elvis will start up in input mode 

Sets the window option’s value to winsize. 


If you use the +command parameter, then after the first file is loaded, command is executed as an Ex 
command. A typical example would be elvis +237 foo, which would cause elvis to start editing 
foo and then move directly to line 237. The -c command variant was added for UNIX SysV 
compatibility. 





During editing, elvis stores text in atemporary file For UNIX, this file will usually be stored in 
the /tmp directory, and the first three characters will be e1v. For other systems, the tenporary files 
may be stored someplace else; see the version-specific section of the documentation. 

This is the database used by the : tags command and the -+ option. It is usually created by the 
ctags(1) program. 

On UNIX-like systems, a file called .exrc in your home directory is executed as a series of ex 
commands. A file by the same name may be executed in the current directory, too. On non-UN IX 
systems, .exrc iSusually an invalid filavame there, the initialization file is called elvis.rc instead. 


Thisis the name of your terminal's entry in the termcap or terminfo database. T he list of legal 
values varies from one system to another. 


Optional. If your system uses termcap, and the Termcap variable is unset, then elvis will read your 
terminal's definition from /etc/termcap. If TeRMcaP is set to the full pathname of a file (starting with 
a /) then elvis will look in the named file instead of /etc/termcap. If TERMCAP is set to a value which 
doesn’t start with a /, then its value is assumed to be the full termcap entry for your terminal. 


Optional. If your system uses terminfo, and the TerMINFo variable is unset, then elvis will read your 
terminal's definition from the database in the /usr/1lib/terminfo database | f TERMINFo is set, then its 
value is used as the database name to use instead of /usr/lib/terminfo. 

O ptional. T hese variables, if set, will override the screen size values given in the termcap/terminfo 
for your terminal. On windowing systems such as X, elvis has other ways of determining the 
screen size, so you should probably leave these variables unset. 

O ptional. This variable can hold ex commands which will be executed instead of the .exre file in 
your home directory. 


Part |: User Commands 


SHELL Optional. The sHeLt variable sets the default value for the she11 option, which determines which 
shell program is used to perform wildcard expansion in filenames, and also which is used to execute 
filters or external programs. The default value on UNIX systems is /bin/sh. 


N ote: Under MS-DOS, this variable is called comspec instead of SHELL. 


HOME This variable should be set to the name of your home directory. elvis looks for its initialization file 
there; if Home is unset, then the initialization file will not be executed. 

TAGPATH O ptional. This variable is used by the ref program, which isinvoked by the shift-k, control-], 
and :tag commands. See ret for more information. 

TMP, TEMP T hese optional environment variables are only used in non-U N IX versions of elvis. T hey allow 


you to supply a directory nameto be used for storing temporary files. 


SEE ALSO 
ctags(1), ref(1), elvprsv(1), elvrec(1) 
Elvis— A Clone of Vi/Ex, the complete elvis documentation. 


BUGS 
Thereisno Lisp support. Certain other features are missing, too. 


Auto-indent mode is not quite compatible with the real vi. Among other things, 0*p and **p don’t do what you might 
expect. 


Long lines are displayed differently. The real vi wraps long lines onto multiple rows of the screen, but elvis scrolls sideways. 


AUTHOR 
Steve Kirkendall (kirkenda@cs.pdx.edu) 


M any other people have worked to port elvis to various operating systems. T 0 see who deserves credit, run the : version 
command from within elvis, or look in the system-specific section of the complete documentation. 


elvprsv 


elvprsv— Preservethe modified version of a file after a crash 


SYNOPSIS 


elvprsv ["-why elvis died"] /tmp/filename... 
elvprsv -R /tmp/filename... 


DESCRIPTION 
elvprsv preserves your edited text after elvis dies. The text can be recovered later, viathe elvprsv program. 


For UN IX-like systems, you should never need to run this program from the command line It is run automatically when 
elvis is about to die and it should berun (via /etc/rc) when the computer is booted. THAT'S ALL! 


For non-U NIX systems such asMS-DOS or VMS, you can ather use elvprsv the same way as under UNIX systems (by 
running it from your AUTOEXEC.BAT file), or you can run it separately with the -r flag to recover the files in onestep. 


If you're editing a file when elvis dies (due to a bug, system crash, power failure, and so on), then elvprsv will preserve the 
most recent version of your text. T he preserved text is stored in a special directory; it does not overwrite your text file 
automatically. (If the preservation directory hasn’t been set up correctly, then elvprsv will simply send you a mail message 
describing how to manually run elvprsv.) 


elvprsv will send mail to any user whose work it preserves, if your operating systen normally supports mail. 


FILES 
/tmp/elv* Thetemporary file that elvis was using when it died. 
/usr/preserve/p* The text that is preserved by elvprsv. 


/usr/preserve/Index A text file which lists the names of all preserved files, and the names of the /usr/preserve/p* files 
that contain their preserved text. 


BUGS 


Due to the permissions on the /usr/preserve directory, on UN IX systems elvprsv must berun as superuser. T his is 
accomplished by making the elvprsv executable be owned by root and turning on its “set user id” bit. 


If you're editing a namdess buffer when elvis dies, then elvprsv will pretend that the file was named foo. 


AUTHOR 


Steve Kirkendall (kirkenda@cs.pdx.edu) 


elvrec 

elvrec— Recover the modified version of a file after a crash 
SYNOPSIS 

elvrec [preservedfile [newfile]] 
DESCRIPTION 


If you're editing a file when elvis dies, the system crashes, or power fails, the most recent version of your text will be 
preserved. T he preserved text is stored in aspecial directory; it does not overwrite your text file automatically. 


The elvrec program locates the preserved version of a given file and writes it over the top of your text file— or to anew file, 
if you prefer. T he recovered file will have nearly all of your changes. 


To seea list of all recoverable files, run elvrec with no arguments. 


NOTE 


If you haven't set up adirectory for file preservation, you'll haveto manually run the elvprsv program instead of elvrec. 


FILES 


/usr/preserve/p* The text that was preserved when elvis died. 
/usr/preserve/Index A text file that lists the names of all preserved files, and the names of the /usr/preserve/p* files that 
contain their preserved text. 


BUGS 
elvrec iS very picky about filenames. You must tal it to recover the file using exactly the same pathname as when you were 
editing it. The simplest way to do this is to go into the same directory that you were editing, and invoke elvrec with the 
same filename as elvis. If that doesn’t work, then try running elvrec with no arguments, to see exactly which pathnameit is 
using for the desired file. 
Dueto the permissionson the /usr/preserve directory, on UN IX systems elvrec must be run as superuser. T hisis 
accomplished by making the elvrec executable be owned by root and setting its “set user id” bit. 


If you're editing a namdess buffer when elvis dies, then elvrec will pretend that the file was named foo. 
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AUTHOR 


Steve Kirkendall (kirkenda@cs.pdx.edu) 


emacs 


emacs— GNU project emacs 


SYNOPSIS 


emacs [ command-line switches ] [ files ... ] 


DESCRIPTION 
GNU emacs isa version of emacs, written by the author of the original (PD P-10) emacs, Richard Stallman. 


The primary documentation of GNU emacs isin theGNU EmacsM anual, which you can read online using info, a 
subsystem of emacs. Please look there for complete and up-to-date documentation. This man page is updated only when 
someone volunteers to do so; the emacs maintainers’ priority goal isto minimize the amount of time this man page takes 
away from other more useful projects. 


The user functionality of GNU emacs encompasses everything other emacs editors do, and it is easily extensible since its 
editing commands are written in Lisp. 


emacs has an extensive interactive hap facility, but the facility assumes that you know how to manipulate emacs windows and 
buffers. C tri-th (backspace or C trl-+h) enters theH elp facility. H ap Tutorial (Ctrith t) requests an interactive tutorial that 
can teach beginners the fundamentals of emacs in a few minutes. H elp Apropos (Ctrl+h a) hdps you find a command given 
its functionality, H dp Character (Ctrl+h c) describes a given character's effect, and H dp Function (Ctrl+h f) describes a 
given Lisp function specified by name 


emacs’SU ndo can undo several steps of modification to your buffers, so it is easy to recover from editing mistakes. 


GNU emacs’s many special packages handle mail reading (rwai1) and sending (mail), outline editing (outline), compiling 
(Compile), running subshells within emacs windows (She11), running a Lisp read-eval-print loop (Lisp-Interaction-Mode), and 
automated psychotherapy (Doctor). 


There is an extensive reference manual, but users of other emacses should have little trouble adapting even without a copy. 
Users new to emacs will be able to use basic features fairly rapidly by studying the tutorial and using the self-documentation 


features. 
OPTIONS 
The following options are of general interest: 
file Edit file. 
+number Go to the line specified by number (do not insert a space between the + sign and the number). 
-q Do not load an init file 
-u user Load user's init file 
-t file Use specified file as the terminal instead of using stdin/stdout. T his must be the first argument specified 


in the command line. 
The following options are Lisp-oriented (these options are processed in the order encountered): 
-f function Execute the Lisp function function. 
-lfile Load the Lisp codein thefilefile. 
The following options are useful when running emacs aS a batch editor: 


-batch Edit in batch mode. The editor will send messages to stdout. This option must be the first in the 
argument list. You must use -1 and -f options to specify files to execute and functions to call. 


-kill Exit emacs whilein batch mode. 


~ & 
USING emacs WITH X 


emacs has been tailored to work well with the X Window System. If you run emacs from under X windows, it will create its 
own X window to display in. You will probably want to start the editor as a background process so that you can continue 
using your original window. 


emacs Can be started with the following X switches: 


-rn name Specifies the program name which should be used when looking up defaults in the 
user’s X resources. This must be the first option specified in the command line. 

-name name Specifies the name that should be assigned to the emacs window. 

-r Display the emacs window in reverse video. 

“i Use the “kitchen sink” bitmap icon when iconifying the emacs window. 

-font font, -fn font Sé& the emacs window’s font to that specified by font. You will find the various X 


fontsin the /usr/1ib/Xx11/fonts directory. N ote that emacs will only accept fixed 
width fonts. Under the X11 Rdease 4 font-naming conventions, any font with the 
value m or c in the eleventh field of the font nameis a fixed width font. Furthermore 
fonts whose name are of the form widthxheight are generally fixed width, asis the 
font fixed. See x1sfonts(1) for more information. 


When you specify a font, be sure to put a space between the switch and the font 


name 

-b pixels Se the emacs window's border width to the number of pixels specified by pixds. 
D efaults to one pixd on each side of the window. 

-ib pixels Sé& the window’s internal border width to the number of pixds specified by pi xels. 
Defaults to one pixd of padding on each side of the window. 

-geometry geometry Se the emacs window's width, haght, and position as specified. The geometry 


specification is in the standard uformat; see x(1) for more information. The width 
and height are specified in characters; the default is 80 by 24. 








-fg color On color displays, sets the color of the text. See the file /usr/1ib/x11/rgb.txt fora 
list of valid color names. 

-bg color On color displays, sets the color of the window’s background. 

-bd color On color displays, sets the color of the window’s border. 

-cr color On color displays, sets the color of the window’s text cursor. 

-ms color On color displays, sets the color of the window’s mouse cursor. 

-d displayname, -display displayname Create the emacs window on the display specified by disp! ayname. M ust be the first 
option specified in the command line 

-nw Tells emacs not to use its special interface to x. If you use this switch when invoking 


emacs from an xterm(1) window, display is done in that window. This must bethe 
first option specified in the command line 


You can set x default values for your emacs windows in your xresources file see xrdb(1). Use the following format: 


emacs.keyword:value 


where val ve specifies the default value of keyword. emacs lets you set default values for the following keywords: 


font (class Font) Sets the window’s text font. 

reverseVideo (Class ReverseVideo) If reverseVideo’s value is set to on, the window will be displayed in reverse video. 
bitmapIcon (Class BitmapIcon) If bitmap! con’s value is set to on, the window will iconify into the “kitchen sink.” 
borderWidth (Class BorderWidth) Sets the window's border width in pixels. 

internalBorder (Class BorderWidth) Sets the window’s internal border width in pixds. 

foreground (Class Foreground) For color displays, sets the window’s text color. 

background (Class Background) For color displays, sets the window’s background color. 


borderColor (class BorderColor) For color displays, sets the color of the window’s border. 
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cursorColor (Class Foreground) For color displays, sets the color of the window’s text cursor. 
pointerColor (Class Foreground) For color displays, sets the color of the window’s mouse cursor. 
geometry (Class Geometry) Sets the geometry of the emacs window. 


title (class Title) 
iconName (Class Title) 


Sets the title of the emacs window. 
Sets the icon name for the emacs window icon. 


If you try to set color values while using a black-and-white display, the window’s characteristics will default as follows: T he 
foreground color will be set to black, the background color will be set to white, the border color will be set to gray, and the 
text and mouse cursors will be set to black. 








USING THE MOUSE 
The following lists the mouse button bindings for the emacs window under X11. 
M ouse Button Function 
left Set point. 
middle Paste text. 
right Cut text into X cut buffer. 
Shift-+middle Cut text into X cut buffer. 
Shift-+right Paste text. 
Ctrl+middle Cut text into X cut buffer and kill it. 
Ctrl-+right Select this window, then split it into two windows. Sameas typing Ctrl+x 2. 
Ctrl+Shifthet X buffer menu; hold the buttons and keys down, wait for menu to appear, select buffer, and 


Ctrl4Shift4middle 
Ctrl4Shift4right 
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rdease. M ove mouse out of menu and release to cancel. 
X hap menu; pop up index card menu for emacs help. 
Select window with mouse, and delete all other windows. Same as typing Ctrl +x 1. 


You can order printed copies of the GNU EmacsM anual from the Free Software Foundation, which develops GN U 
software. See the file orvers for ordering information. 


Your local emacs maintainer might also have copies available As with all software and publications from FSF, everyoneis 
permitted to make and distribute copies of the emacs manual. The TeX source to the manual is also included in the emacs 


source distribution. 


FILES 

/usr/local/info Files for the info documentation browser (a subsystem of emacs) to 
refer to. Currently not much of UNIX is documented here, but the 
complete text of the emacs reference manual is included in a 
convenient tree structured form. 

/usr/local/1ib/emacs/$VERSION/src C source files and object files. 

/usr/local/lib/emacs/$VERSION/lisp Lisp source files and compiled files that define most editing com- 
mands. Some are preloaded; others are autoloaded from this directory 
when used. 

/usr/local/lib/emacs/$VERSION/etc Various programs that are used with GNU emacs, and some files of 
information. 

/usr/local/lib/emacs/$VERSION/etc/DOC.* Contains the documentation strings for the Lisp primitives and 


preloaded Lisp functions of GNU emacs. They are stored here to 
reduce the size of emacs prope’. 


/usr/local/lib/emacs/$VERSION/etc/DIFF Discusses GN U emacs versus T wenex emacs. 
/usr/local/lib/emacs/$VERSION/etc/CCADIFF Discusses GNU emacs versus CCA emacs. 
/usr/local/1ib/emacs/$VERSION/etc /GOSDIFF Discusses GNU emacs versus Gosling emacs. 
/usr/local/1ib/emacs/$VERSION/etc /SERVICE Lists people offering various services to assist users of GNU emacs, 


including education, troubleshooting, porting, and customization. 
T hese files also have information useful to anyone wanting to write 
programs in the emacs Lisp extension language, which has not yet 
been fully documented. 
/usr/local/lib/emacs/lock H olds lock files that are made for all files being modified in emacs, to 
prevent simultaneous modification of one file by two users. 
/usr/local/lib/emacs/$VERSION/$ARCHITECTURE/cpp § Th@GNU cpp, needed for building emacs on certain versions of 
UNIX where the standard cpp cannot handle long names for macros. 
/usr/1ib/X11/rgb.txt List of valid x color names. 


BUGS 


There is a mailing list, bug-gnu-emacs@prep.ai.mit.edu on the Internet (ucbvax!prep.ai.mit.edu!bug-gnu-emacs ON 
UUCPna), for reporting emacs bugs and fixes. But before reporting something as a bug, please try to be sure that it really isa 
bug, not a misunderstanding or a ddiberate feature. W eask you to read the section “Reporting emacs Bugs” near the end of 
the reference manual (or info system) for hints on how and when to report bugs. Also, include the version number of the 
emacs yOu are running in every bug report that you send in. 


Do not expect a personal answer to a bug report. The purpose of reporting bugs is to get them fixed for everyone in the next 
release, if possible For personal assistance, look in the service file for a list of people who offer it. 


Please do not send anything but bug reports to this mailing list. Send requests to be added to mailing lists to the special list 
info-gnu-emacs-request@prep.ai.mit.edu (or the corresponding UUCP address). For more information about emacs mailing 
lists, see the file /usr/local/emacs/etc/MAILINGLISTS. Bugs tend actually to be fixed if they can be isolated, so it isin your 
interest to report them in such a way that they can be easily reproduced. 


One bug that | know about: Shel will not work with programs running in Raw mode on someUN |X versions. 


UNRESTRICTIONS 


emacs iS free, anyone may redistribute copies of emacs to anyone under the terms stated in the emacs General Public License, a 
copy of which accompanies each copy of emacs and which also appears in the reference manual. 


Copies of emacs may sometimes be received packaged with distributions of UNIX systems, but it is never included in the 
scope of any license covering those systems. Such inclusion violates the terms on which distribution is permitted. In fact, the 
primary purpose of the General Public Licenseisto prohibit anyone from attaching any other restrictions to redistribution 
of emacs. 


Richard Stallman encourages you to improve and extend emacs, and urges that you contribute your extensions to the GN U 
library. Eventually GNU (GNU’sN ot UNIX) will beacomplete replacenent for Berkdey UNIX. Everyone will be free to 
use, copy, study, and changethe GN U system. 

SEE ALSO 


X(1), x1sfonts(1), xterm(1), xrdb(1) 


AUTHORS 


emacs was written by Richard Stallman and the Free Software Foundation. Joachim M artillo and Robert K rawitz added the X 
features. 


19 April 1994 
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emacstool 


emacstool— Run emacs under Sun windows with function key and mouse support. 


SYNOPSIS 


emacstool [{window_args} {-rc run_command_path} args ... ] 


TYPICAL USAGE 
In ~/.suntools Or ~/.rootmenu, include aline like this: 


“Emacstool" emacstool -WI emacs.icon -f emacstool-init 


DESCRIPTION 


emacstool creates a SunV iew frame and a tty subwindow within which mouse events and function keys are translated to 
ASCII sequences that emacs can parse. The translated input events are sent to the process running in the tty subwindow, 
which is typically GNU emacs. emacstoo1 thereby allows GNU emacs users to make full use of the mouse and function keys. 
GNU emacs can be loaded with functions to interpret the mouse and function-key events to make a truly fine screen-oriented 
editor for the Sun W orkstation. 


NOTE 


GNU emacs has a special interface to the X Window System as well. The X Window System has many technical advan- 
tages, it is an industry standard, and it is also free software. T he F ree Software F oundation urges you to try X Windows, 
and distributes a free copy of x on emacs distribution tapes. 


Function keys are translated to a sequence of the form *x*[a-o][1rt]. The last character is 1, r, or t, corresponding to 
whether the key isamong the Lett, Right, or T op function keys. Thethird character indicates which button of the group was 
pressed. T hus, the function key in thelower-right corner will transmit the sequence *x*or. In addition, the [irt] is affected 
by the Control, M eta, and Shift keys. Unshifted Ctrl keys will be nonalphabetic: C-l is [,], C-ris [2], C-t is [4]. 


M ouse buttons are encoded as *x"@([{124] x y)\n. *x*@isthe standard GNU emacs mouse event prefix; it is followed by alist 
indicating the button pressed and the character row and column of the point in the window where the mouse cursor is, and 
followed by a newline character. In GNU emacs, the *x*@ dispatches to a mouse event handler which then reads the following 
list. 

OPTIONS 
emacstool supports all the standard window arguments, including font and icon specifiers. 
By default, emacstoo1 runs the program emacs in the created subwindow. The value of the environment variable EwacsTooL 
can be used to override this if your version of emacs is not accessible on your search path by the name emacs. In addition, the 


run command can be set by the pathname following the last occurrence of the -rc flag. This is convenient for using emacstool 
to run on remote machines. 


All other command-line arguments not used by the window system are passed as arguments to the program that runsin the 
emacstool window. 
For example, 


local% (emacstool -rc rlogin remote -8 &)& 


will create an emacstool window logged in to amachine named remote. If emacs isrun from this window, emacstool will 
encode mouse and function keys, and send them to riogin. If emacs isrun from this shell on the ranote machine, it will see 
the mouse and function keys properly. H owever, since the remote host does not have access to the screen, the cursor cannot 
be changed, menus will not appear, and the selection buffer (stuFF) is limited. 


~ BF 
USING WITH GNU emacs 


TheGNU emacs files lisp/term/sun.el, lisp/sun-mouse.el, lisp/sun-fns.el, and src/sunfns.c provide emacs Support 

for the emacstoo1 and function keys. emacstoo1 will automatically set the Term environment variable to be sun and unset 

the environment variable Termcap. T hat is, these variables will not be inherited from the shal that starts emacstoo1. Since the 
terminal type is sun (that is, the environment variable Term is set to sun), emacs will automatically load the file 1isp/term/sun. 
This, in turn, will ensure that sun-mouse.e1 is autoloaded when any mouse events are detected. It is suggested that sun-mouse 
and sun-fns be loaded in your site-init.e1 file, so that they will always be loaded when running on a Sun workstation. 


In addition, emacstoo1 sets the environment variable 1n_EMACSTOOL = "t". Lisp codein your ~/.emacs Can use (getenv 
"IN EMACSTOOL") to determine whether to do emacstool-specific initialization. sun.e1 uses this to automatically call emacstool - 
init if (getenv "IN_EMACSTOOL") is defined. 


The file src/sunfns.c defines several useful functions for emacs on the Sun. Among these are procedures to pop up SunView 
menus, put and get from the SunView sturF buffer, and a procedure for changing the cursor icon. If you want to define or 
edit cursor icons, there is arudimentary mouse-driven icon editor in thefile 1isp/sun-cursors.el. T ry invoking (sc:edit- 
cursor). 


BUGS 


It takes a few milliseconds to create a menu before it pops up. 


ENVIRONMENT VARIABLES 


EMACSTOOL, IN_EMACSTOOL, TERM, TERMCAP 


FILES 


emacs 


SEE ALSO 


emacs(1), .../etc/SUN-SUPPORT, .../lisp/term/sun.el 


etags 
etags— Generate tag file for emacs 
ags— Generate tag file for vi 


SYNOPSIS 


etags [ -aCDSVH] [ -i file ][-o tagfile ] 
[ --ct++ ] [ --no-defines] [ --ignore-indentation ] [ --help ] [ --version ] 
[ --include=file ] [ --output=tagfile ] [ --append ] file ... 


ro} 





ctags [ -aCdSVH] [ -BtTuvwx ] [ -o tagfile ] 

[ --ct++ ] [ --defines ] [ --ignore-indentation ] 

[ --backward-search] [ --forward-search ] [ --typedefs ] [ --typedefs-and-ct++] 
[ --no-warn ] [ --cxref ] [ --help ] [ --version ] 

[ --output=tagfile ] [ --append ] [ --update ] file ... 





DESCRIPTION 


The etags program is used to create a tag table file, in a format understood by emacs(1); the ctags program is used to create a 
similar table in a format understood by vi(1) . Both forms of the program understand the syntax of C, FORT RAN, Pascal, 
LaTeX, Scheme, emacs Lisop/Common Lisp, and most assembler-like syntaxes. Both forms read the files specified on the 
command line, and write a tag table (defaults: Tacs for etags, tags for ctags) in the current working directory. The programs 
recognize the language used in an input file based on its fileaame and contents; there are no switches for specifying the 
language. 
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OPTIONS 


Some options make sense only for the vi-style tag files produced by ctags; etags does not recognize them. The programs 
accept unambiguous abbreviations for long option names. 


-a, 


-B, 


-d, 


-D, 


-append 


-backward-search 


--0t+ 


-defines 


-no-defines 


file, --include=file 


tagfile, --output=tagfile 


-ignore-indentation 


-t, --typedefs 
-T, --typedefs-and-ct+ 
-u, --update 
-v, --vgrind 
-w, --no-warn 
-x, --cxref 
-H, --help 
-V, --version 
SEE ALSO 


Append to existing tag file. (For vi-format tag files, see also - -update.) 

T ag files written in the format expected by vi contain regular expression search instructions; 
the -8 option writes them using the delimiter 2, to search backwards through files. The 
default is to use the ddimiter / to search forwards through files. O nly ctags accepts this 
option. 

Treat files with .c and .h extensions as C-++- code, not C code. Files with .c, .H, .cxx, .hxx, 
or .cc extensions are always assumed to be C ++ code 

Create tag entries for C preprocessor definitions, too. This is the default behavior for etags, 
so this option is only accepted by ctags. 

Do not create tag entries for C preprocessor definitions. T his may make the tags file much 
smaller if many header files are tagged. T his is the default behavior for ctags, so this option 
is only accepted by etags. 

Include a note in tag file indicating that, when searching for a tag, one should also consult 
the tags filefi le after checking the current file Only etags accepts this option. 

Explicit name of file for tag table, overrides default Tacs or tags. (But ignored with -v or 
-x.) 

Don’t rely on indentation as much as we normally do. Currently, this means not to assume 
that aclosing brace in the first column is the final brace of a function or structure definition 
inC mdCH. 

Record typedefs in C code as tags. Since this is the default behavior of etags, only ctags 
accepts this option. 

Generate tag entries for typedefs, struct, enum, and union tags, and C++ member functions. 
Since this is the default behavior of etags, only ctags accepts this option. 

Update tag entries for files specified on command line leaving tag entries for other files in 
place. Currently, this isimplemented by deleting the existing entries for the given files and 
then rewriting the new entries at the end of the tags file. It is often faster to simply rebuild 
the entire tag file than to use this. Only ctags accepts this option. 

Instead of generating a tag file, write index (in vgrind format) to standard output. Only 
ctags accepts this option. 
Suppress warning messages about duplicate entries. The etags program does not check for 
duplicate entries, so this option is not allowed with it. 

Instead of generating a tag file, write a cross-reference (in cxref format) to standard output. 
Only ctags accepts this option. 


Print usage information. 


Print the current version of the program (same as the version of the emacs etags is shipped 
with). 








emacs entry in info; GNU EmacsM anual, Richard Stallman. 


exref(1), emacs(1), vgrind(1), vi(1). 


COPYING 


Copyright © 1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
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Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


GNU Tools, 19 April 1994 


expand 


expand— C onvert tabs to spaces 


SYNOPSIS 
expand [-tabl[,tab2[,...]]] [-t tabl[,tab2[,...]]] [-i] [—tabs=tabl[,tab2[,...]]] 
[--initial] [--help] [--version] [file...] 

DESCRIPTION 


This manual page documents the GN U version of expand. expand writes the contents of each given file or the standard input 
if none are given or when a file named - is given, to the standard output, with tab characters converted to the appropriate 
number of spaces. By default, expand converts all tabs to spaces. I t preserves backspace characters in the output; they 
decrement the column count for tab calculations. T he default action is equivalent to -s (set tabs every 8 columns). 


OPTIONS 

-, -t, --tabs tabl[,tab2[,...]] If only one tab sop isgiven, set the tabst ab1 spaces apart instead of the default s. 
Otherwise, set the tabs at columns tab1, tab2, and so forth (numbered from 0) and 
replace any tabs beyond the tab stops given with single spaces. If the tab-stops are 
specified with the -t or --tabs option, they can be separated by blanks as well as by 
commas. 

-i, --initial Only convert initial tabs (those that precede all nonspace or tab characters) on each 
lineto spaces. 

--help Print a usage message and exit with anonzevo status. 

--version Print version information on standard output then exit. 


GNU Text Utilities 


find 
find— Search for files in a directory hierarchy 


SYNOPSIS 


find [path...] [expression] 


DESCRIPTION 


This manual page documents the GN U version of find. find searches the directory tree rooted at each given filename by 
evaluating the given expression from left to right, according to the rules of precedence (see “O perators,” later in this manual 
page), until the outcome is known (the left side is False for anp operations, True for or), at which point find moves on to the 
next filename 


The first argument that begins with -, (, ), ,, or ! istaken to be the beginning of the expression; any arguments before it are 
paths to search, and any arguments after it are the rest of the expression. If no paths are given, the current directory is used. If 
no expression is given, the expression -print is used. 


find exits with status @ if all files are processed successfully, greater than o if errors occur. 
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EXPRESSIONS 


The expression is made up of options (which affect overall operation rather than the processing of a specific file, and always 
return True), tests (which return a True Or False value), and actions (which have side effects and return a True Or False value), 
all separated by operators. -and is assumed where the operator is omitted. If the expression contains no actions other than - 
prune, -print iS performed on all files for which the expression is true 


OPTIONS 


All options always return True. T hey always take effect, rather than being processed only when ther placein the expression is 
reached. Therefore for clarity, it is best to place them at the beginning of the expression. 


-daystart 
-depth 
-follow 


-help, —help 


-maxdepth | evel s 
-mindepth | evel s 
-mount 


-noleaf 


-version, —version 


-xdev 


TESTS 


M easure times (for -amin, -atime, -cmin, -ctime, -mmin, and -mtime) from the beginning of today 
rather than from 24 hours ago. 

Process each directory’s contents before the directory itself. 

D ereference symbolic links. Implies -noleaf. 

Print asummary of the command-line usage of find and exit. 


Descend at most | evel s (anonnegative integer) levels of directories below the command-line 
arguments. -maxdepth @ means only apply the tests and actions to the command-line arguments. 

Do not apply any tests or actions at leves less than | evel s (anonnegative integer). -mindepth 1 
means process all files except the command-line arguments. 

Don’t descend directories on other filesystems. An alternate name for -xdev, for compatibility with 
some other versions of find. 

Do not optimize by assuming that directories contain two fewer subdirectories than their hard link 
count. T his option is needed when searching filesystems that do not follow the UNIX directory- 
link convention, such asCD-ROM or MS-DOS filesystems or AFS volume mount points. Each 
directory on anormal UN IX filesystem has at least 2 hard links: its name and its . entry. Addition- 
ally, its subdirectories (if any) each havea .. entry linked to that directory. W hen find is examining 
a directory, after it has statted two fewer subdirectories than the directory’s link count, it knows 
that the rest of the entries in the directory are nondirectories (1eat files in the directory tree). If 
only the files names need to be examined, there is no need to stat them; this gives a significant 
increase in search speed. 

Print the find version number and exit. 

Don’t descend directories on other filesystems. 


Numeric arguments can be specified as 


+n 
-n 
n 
-amin n 


-anewer file 


-atime n 
-cmin n 


-cnewer file 


-ctime n 
-empty 
-false 


Greater than n. 

Less than n. 

Exactly n. 

File was last accessed n minutes ago. 


File was last accessed more recently than fi! e was modified. -anewer is affected by -follow only if - 
follow comes before -anewer on the command line. 


ile was last accessed n *24 hours ago. 
ile’s status was last changed n minutes ago. 


F 

F 

File’s status was last changed more recently than file was modified. -cnewer is affected by -follow 
only if -fo11ow comes before -cnewer on the command line 
F 
F 
A 


ile’s status was last changed n*24 hours ago. 
ileis empty and is either a regular file or a directory. 
ways false. 








-fstype type 


-gid n 
-group gname 
-ilname pattern 


-iname pattern 


-inum n 
-ipath pattern 
-iregex pattern 


-links n 








-lname 


2 


ern 





-mmin n 
-mtime n 


-name pattern 


-newer file 


-nouser 


-nogroup 
-path pattern 


-perm mode 


-perm -mode 
-perm +mode 


-regex pattern 


-size n[bckw] 


-true 
-type c 


find 


Fileis on a filesystem of typet ype. T he valid filesystem types vary among different versions of 
UNIX; an incomplete list of filesystem types that are accepted on some version of UNIX or anothe 
iS: ufs, 4.2, 4.3, nfs, tmp, mfs, $51K, $52k. YOU Can use -printf with ther directive to see the types 
of your filesystems. 


ile's numeric group ID isn. 
File belongs to group gname (numeric group |D allowed). 
ike -1name, but the match is case-insensitive. 


L 
Like -name, but the match is case-insensitive. For example, the patterns fo* and F2? match the 
filenames Foo, FOO, foo, f00, and SO on. 


nm 


Filehas inode number n. 

Like -path, but the match is case-insensitive. 

Like -regex, but the match is case-insensitive. 

Filehasn links. 

Fileis a symbolic link whose contents match shell pattern pat t ern. The meta characters do not treat 
/ or . specially. 

File’s data was last modified n minutes ago. 

e's data was last modified n*24 hours ago. 


Base of filename (the path with the leading directories removed) matches shell pattern pattern. The 
meta characters (*, ?, and []) do not match a. at thestart of the base name. T 0 ignore a directory 
and the files under it, use -prune; see an example in the description of -path. 


File was modified more recently than file. -newer is affected by -follow only if -follow comes before 
-newer on the command line. 


N o user corresponds to file's numeric user ID. 
No group corresponds to file's numeric group ID. 


Filename matches shal pattern pattern. T he meta characters do not treat / or . specially; so, for 
example, 

find . - path ‘./sr*sc’ 

will print an entry for adirectory called ./src/misc (if one exists). T o ignore a whole directory tree, 
use -prune rather than checking every file in thetree. For example to xip the directory src/emacs 
and all files and directories under it, and print the names of the other files found, do something like 
this: 
find . - path ‘./src/emacs’ -prune -o -print 


Files permission bits are exactly mode (octal or symbolic). Symbolic modes use mode ea as a point 
of departure. 


of the permission bits mode are set for the file 
ny of the permission bits mode are set for the file 


Filename matches regular expression pattern. Thisis a match on the whole path, not a search. For 
example, to match a filenamed ./fubar3, you can use the regular expression .*bar. or .*b.*3, but 
Ot b.*r3. 


n 
File uses n units of space The units are 512-byte blocks by default or if b followsn, bytes if c 
b 








nm 


A 
A 


o 


follows n, kilobytes if k follows n, or 2-byte words if w followsn. T he size does not count indirect 
ocks, but it does count blocks in sparse files that are not actually allocated. 


Always true. 

Fileis of type c. Possible types: 

b Block (buffered) special 

c Character (unbuffered) special 
d Directory 

p Named pipe (FIFO) 
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-uid n 
-used n 
-user uname 


-xtype c 


ACTIONS 


-exec command ; 


-fls file 
-fprint file 


-fprintd file 
-fprintf file format 


-ok command ; 


-print 


-printo 


-printf format 


¢ Regular file! symbolic link 
s Socke 


Files numeric user ID isn. 
File was last accessed n days after its status was last changed. 
Fileis owned by user uname (numeric user ID allowed). 


The same as -type unless the file is a symbolic link. For symbolic links: if -follow has not been 
given, True if the file isa link to a file of type c; if -fol1ow has been given, True if c is1.1n other 
words, for symbolic links, -xtype checks the type of the file that -type does not check. 


Execute command; True if @ status is returned. All following arguments to find are taken to be 
arguments to the command until an argument consisting of ; is encountered. The string {} is 
replaced by the current filename being processed everywhere it occurs in the arguments to the 
command, not just in arguments where it is alone, as in some versions of find. Both of these 
constructions might need to be escaped (with a \) nor quoted to protect them from expansion by 
the shell. The command is executed in the starting directory. 


True; like -1s but write to file like -fprint. 


True; print the full filavame into filefile. If file does not exist when fina isrun, it is created; if it 
does exist, it istruncated. T he filenames /dev/stdout and /dev/stderr are handled specially; they 
refer to the standard output and standard error output, respective y. 


True; like -printo but write to file like -fprint. 
True; like -printf but write to file like -fprint. 


Like -exec but ask the user first (on the standard input); if the response does not start with y or y, 
do not run the command, and return False. 


True; print the full filevame on the standard output, followed by anewline 


True; print the full filavame on the standard output, followed by a null character. T his allows 
filenames that contain newlines to be correctly interpreted by programs that process the find 
output. 


True; print format on the standard output, interpreting n escapes and » directives. Field widths and 
precisions can be specified as with the printf C function. Unlike -print, -printt does not add a 
newline at the end of the string. The escapes and directives are as follows: 


\a_ Alarm bell 

\b Backspace 

\c Stop printing from this format immediately and flush the output 
\f Form feed 

\n Newline 

\r Carriage return 

\t Horizontal tab 

\v Vertical tab 

\\ A literal backslash (‘\’) 


A \ character followed by any other character is treated as an ordinary character, so they both are 
printed: 

%% A literal percent sign. 

%a Files last access time in the format returned by the C ctime function. 


*Ak File’s last access time in the format specified by k, which is either e or a directive for the C 
strftime function. T he possible values for k are listed below; some of them might not be 
available on all systems, due to differences in strftime between systens. 


@ seconds since] an. 1, 1970, 00:00 GMT. 


ce LC LC & 
jo 


Q 


oe 


a 


oe 


a 


oe 


a 


oe 


a> @ 


oe 


oe 


x 


Bp. 


oe 


x 


oe 


aA 


oe 


find 


Time fields 





H our (00. .23) 

H our (01..12) 

H our (0. .23) 

H our (1..12) 

M inute (a0. .59) 

Locale’s a.m. or p.m. 

Time 12-hour (hh:mm:ss [AP]M) 
Second (00. .61) 

Time 24-hour (hh:mm:ss) 

Locale’s time representation (H:m:s) 


Timezone (for example, EDT), or nothing if no time zoneis 
determinable 


37 OU SRP FH = 


N «~ Ac 


Date fidds: 





Locale’s abbreviated weekday name (sun. .Sat) 

Locale’s full weekday name, variable length (sunday. .Saturday) 
Locale’s abbreviated month name (van. .Dec) 

Locale’s full month name, variable length (January.. December) 
Locale’s date and time (Sat Nov 04 12:02:33 EST 1989) 

D ay of month (01..31) 

D ate (mm/dd/yy) 

Same aS b 

D ay of year (001. .366) 

M onth (01. .12) 

W eek number of year with Sunday as first day of week (00. .53) 
D ay of week (0. .6) 

W eek number of year with M onday as first day of week (00. .53) 
Locale’s date representation (mm/dd/yy) 

y Last two digits of year (00. .99) 

Y Year (1970...) 


File’s size in 512-byte blocks (rounded up). 

File’s last status change time in the format returned by the C ctime function. 

File’s last status change time in the format specified by k, which isthe same as for %a. 
Files depth in the directory tree; a means the file is a command-line argument. 
Files name with any leading directories removed (only the last element). 

T ype of the filesysten the file is on; this value can be used for -fstype. 

File’s group name, or numeric group ID if the group has no name. 
F 
L 
C 
F 
F 


zs 0 a2 0030 SF > wD 


=e cs 


x 


ile's numeric group ID. 
eading directories of file's name (all but the last element). 
ommand-line argument under which file was found. 
ile's inode number (in decimal). 
ile's sizein 1K blocks (rounded up). 
O bject of symbolic link (empty string if file is not a symbolic link). 
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Files permission bits (in octal). 
N umber of hard links to file. 
F 
F 


oe 
= 


oe 
S 


ile's name 


ile’s name with the name of the command-line argument under which it was found 
removed. 


ile’s size in bytes. 

ile’'s last modification time in the format returned by theC ctime function. 

ile’'s last modification time in the format specified by k, which is the same as for sa. 
e's username, or numevic user ID if the user has no name 

ile's numeric user ID. 


% character followed by any other character is discarded (but the other character is 
printed). 


oe 
nol 


oe 
Uv 


oe 
+t 


oe 
4 
baw 





ce 
(han 
roma TTT 





If -depth isnot given, True; do not descend the current directory. 
If -depth iSgiven, False; no effect. 


True; list current filein 1s -dils format on standard output. The block counts are of 1K blocks, 
unless the environment variable posrxLy_correcT is set, in which case512- byte blocks are used. 


Listed in order of decreasing precedence 





-prune 
-ls 
OPERATORS 
(expr ) 
! expr 
-not expr 
exprl expr2 
exprl -a expr2 
exprl -and expr2 
exprl -o expr2 
exprl -or expr2 
exprl, expr2 
SEE ALSO 


Force precedence. 

True if expr is false. 

Same as! expr. 

And (implied); expr2 isnot evaluated if expr1 isfalse. 
Same aSexprl expr2. 

Same aS exprl expr2. 

Or; expr2 isnot evaluated if expri istrue. 

Same aSexprl -o expr2. 


List; both expr1 and expr2 are always evaluated. The value of expr1 is discarded; the value of the list 
is the value of expr2. 


locate(1L), locatedb(5L), updatedb(1L), xargs(1L) Finding Files (onlinein info, or printed) 
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fitstopnm 


fitstopnm— Convat aFITS file into a portable anymap 


SYNOPSIS 


fitstopnm [-image N][-noraw][-scanmax][-printmax][-min f][-max f][FITSfile] 


DESCRIPTION 
Reads a FITS file asinput. Produces a portable pixmap if the FITS file consists of 3 image planes (NAxIs = 3 and NAXIS3 = 3), 
a portable graymap if the FITS file consists of 2 image planes (Naxrs = 2), or whenever the -image flag is specified. The 
results may need to be flipped top for bottom; if so, just pipe the output through pnmflip -tb. 


fold 
OPTIONS 


The -image option is for FITS files with three axes. T he assumption is that the third axis is for multiple images, and this 
option lets you select which one you want. 


Flags -min and -max can be used to override the min and max values as read from the FITS header or the image data if no 
DATAMIN and DATAMAX Keywords are found. Flag -scanmax can be used to force the program to scan the data even when DATAMIN 
and patamax are found in the header. If -printmax is specified, the program will just print the min and max values and quit. 
Flag -noraw can be used to force the program to produce an ASCII portable anymap. 


The program will tal what kind of anymap is writing. All flags can be abbreviated to their shortest unique prefix. 


REFERENCES 


FIT S stands for Flexible Image Transport System. A full description can be found in Astronomy & Astrophysics Supplement 
Series44 (1981), page 363. 


SEE ALSO 


pnmtofits(1), pgm(5), pnmflip(1) 


AUTHOR 


Copyright © 1989 by J ef Poskanzer, with modifications by D aniel Briggs (dbriggs@nrao.edu) and Alberto Accomazzi 
(alberto@cfa. harvard. edu) 


20 September 1989 


fmt 


fmt— Adjust line length for paragraphs of text 
SYNOPSIS 


fmt [-width][files]... 


DESCRIPTION 


fmt isasimpletext formatter. It inserts or deletes newlines, as necessary, to make all lines in a paragraph be approximately the 
same width. It preserves indentation and word spacing. 


The default line width is 72 characters. You can override this with the -wiath flag. If you don’t name any files on the 
command line, then fmt will read from stdin. 


It istypically used from within vi to adjust the line breaks in a single paragraph. To do this, movethecursor to the top of 
the paragraph, type !gfmt, and press Return. 


AUTHOR 


Steve Kirkendall (kirkenda@cs.pdx.edu) 


fold 


fold— W rap each input line to fit in specified width 
SYNOPSIS 


fold [-bs] [-w width] [—bytes] [—spaces] [—width=wi dth] [—help] 
{-—version] [file...] 
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DESCRIPTION 


This manual page documents the GN U version of fold. fold prints the specified files, or the standard input when no files are 
given or the filename - is encountered, on the standard output. It breaks long lines into multiple shorter lines by inserting a 
newline at column 80. It counts screen columns, so tab characters usually take more than one column, backspace characters 
decrease the column count, and carriage return characters set the column count back to zero. 


OPTIONS 

-b, —bytes Count bytes rather than columns, so that tabs, backspaces, and carriage returns are each counted as 
taking up one column, just like other characters. 

-s, —spaces Break at word boundaries. If the line contains any blanks, thelineis broken after the last blank that 
falls within the maximum line length. If there are no blanks, the line is broken at the maximum 
line length, as usual. 

-w, —width width Use amaximum line length of width columns instead of 80. 

—help Print ausage message and exit with anonzevo status. 

—version Print version information on standard output then exit. 
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free 
free— Display amount of free and used memory in the systten 
SYNOPSIS 
free [-b | -k | -m] [-0] [-s delay] [-t] 
DESCRIPTION 
free displays the total amount of free and used physical and swap memory in the system, as well as the shared memory and 
buffers used by the kernel. 
OPTIONS 


The -b switch displays the amount of memory in bytes; the -k switch (set by default) displays it in kilobytes; the -m switch 
displays it in megabytes. 


The -t switch displays a line containing the totals. 


The -o switch disables the display of a “buffer adjusted” line Unless specified free subtracts/adds buffer menory from/to the 
used/free memory reports (respective y!). 


The -s switch activates continuous polling delay seconds apart. You may actually specify any floating point number for 
delay, usleep(3) is used for microsecond resolution delay times. 


FILES 


/proc/meminfo M emory information 
SEE ALSO 

ps(1), top(1) 
AUTHORS 


Brian Edmonds 
Cohesive Systems, 20 M arch 1993 


fdsfonts 


fsinfo 


fsinfo— x font server information utility 


SYNOPSIS 


fsinfo [-server servername ] 


DESCRIPTION 


fsinfo iS a utility for displaying information about an X font server. It is used to examine the capabilities of aserver, the 
predefined values for various parameters used in communicating between clients and the serve, and the font catalogues and 
alternate servers that are available. 


EXAMPLE 
The following isa sample produced by fsinfo. 


name of server: hansen:7100 

version number: 1 

vendor string: Font Server Prototype 
vendor release number: 17 

maximum request size: 16384 longwords (65536 bytes) 
number of catalogues: 1 

all 

Number of alternate servers: 2 

#0 hansen:7101 

#1 hansen:7102 

number of extensions: 0 


ENVIRONMENT 


FONTSERVER To get the default fontserver 


SEE ALSO 


xfs(1), fs1sfonts(1) 


AUTHOR 
D ave Lemke (N etwork C omputing D evices, Inc.) 
X Version 11 Release 6 


fslsfonts 


fslsfonts— List fonts served by X font server 


SYNOPSIS 


fslsfonts [-options ...] [-fn pattern] 


DESCRIPTION 


fslsfonts lists the fonts that match the given pattern. The wildcard character * may be used to match any sequence of 
characters (including none), and 2 to match any single character. If no pattern is given, * is assumed. 


The* and ? characters must be quoted to prevent them from being expanded by the shell. 
OPTIONS 


-server host: port This option specifies the X font server to contact. 
-1 Lists some attributes of the font on onelinein addition to its name 
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-11 Lists font propertiesin addition to -1 output. 
-111 Supported for compatibility with x1sfonts, but output is the same as for -11. 
=m This option indicates that long listings should also print the minimum and maximum bounds of 
each font. 
-C This option indicates that listings should use multiple columns. This isthe same as-n a. 
-1 This option indicates that listings should use a single column. Thisisthe same as-n 1. 
-w width This option specifies the width in characters that should be used in figuring out how many 
columns to print. T he default is 79. 
-n columns This option specifies the number of columns to use in displaying the output. T he default is a, 
which will attempt to fit as many columns of font names into thenumber of character specified by 
-w width. 
-u This option indicates that the output should be left unsorted. 
SEE ALSO 
xfs(1), showfont(1), x1sfonts(1) 
ENVIRONMENT 
FONTSERVER To get the default host and port to use 
BUGS 


Doing fslsfonts -1 can tieup your server for a very long time. Thisis really a bug with single threaded nonpreemptable 
servers, not with this program. 


AUTHOR 
D ave Lemke (N etwork C omputing D evices, Inc.) 
X Version 11 Rdease 6 1 


fstobdf 


fstobdf— Generate BDF font from X font server 


SYNOPSIS 


fstobdf [ -server server ] -fn fontname 


DESCRIPTION 


The fstobdf program reads a font from a font server and prints a BDF fileon the standard output that may be used to 
recreate the font. This is useful in testing servers, debugging font metrics, and reproducing lost BDF files. 


OPTIONS 

-server servername This option specifies the server from which the font should be read. 

-fn fontname This option specifies the font for which aBD F file should be generated. 
ENVIRONMENT 

FONTSERVER D efault server to use 
SEE ALSO 


xfs(1), bdftopet(1), fslsfonts(1) 


ftp 147 


AUTHOR 
O laf Brandt (N ework Computing D evices), D ave Lemke (N etwork Computing D evices), Jim Fulton (MIT X Consortium) 


X Version 11 Rdease 6 


fstopgm 


fstopgm— Convert aU senix FaceSaver file into a portable graymap 


SYNOPSIS 
fstopgm [fsfile] 
DESCRIPTION 


Reads a U senix FaceSaver file as input. Produces a portable graymap as output. 


FaceSaver files sometimes have rectangular pixe's. Although fstopgm won't rescale them into square pixels for you, it will give 
you the precise pnmscale command that will do the job. Because of this, reading a F aceSaver image is a two-step process. 
First you do 


stopgm > /dev/null 
This will tal you whether you need to use pnmscale. T hen use one of the following pipdines: 


stopgm | pgmnorm 
stopgm | pnmscale -whatever | pgmnorm 


To go to PBM, you want something more like one of these: 


stopgm | pnmenlarge 3 | pgmnorm | pgmtopbm 
stopgm | pnmenlarge 3 | pnmscale <whatever> | pgmnorm | pgmtopbm 


You want to enlarge when going to a bitmap because otherwise you lose information; but enlarging by more than 3 does not 
ook good. 





FaceSaver is a registered trademark of M eron Computerware Ltd. of Oakland, CA. 
SEE ALSO 


pgmtofs(1), pgm(5), pgmnorm(1), pnmenlarge(1), pnmscale(1), pgmtopbm(1) 


AUTHOR 
Copyright © 1989 by J ef Poskanzer 
6 April 1989 


ftp— ARPAné file transfer program 
SYNOPSIS 


ftp [-v] [-d] [-i] [-n] [-g] [host] 


DESCRIPTION 


ftp isthe user interface to the AR PAnet standard File T ransfer Protocol. T he program allows a user to transfer files to and 
from a remote network site. 


O ptions may be specified at the command line, or to the command interpreter. 


Part |: User Commands 


“Vv 


“a 
-d 
“g 


Verbose option forces ftp to show all responses from theremote server, as well as 
report on data transfer statistics. 

Restrains ftp from attempting auto-login upon initial connection. If auto-login is 
enabled, ftp will check the (see below) file in the user’s home directory for an entry 
describing an account on the remote machine. If no entry exists, ftp will prompt for 
the renote machinelogin name (default is the user identity on the local machine), 
and, if necessary, prompt for a password and an account with which to login. 

Turns off interactive prompting during multiple file transfers. 

Enables debugging. 

Disables filename globbing. 


The client host with which ftp isto communicate may be specified on the command line If this is done, ftp will immedi- 
ately attempt to establish a connection to an FTP server on that host; otherwise, ftp will enter its command interpreter and 
await instructions from the user. W hen ftp is awaiting commands from the user, the prompt 


ftp> 


is provided to the user. T he following commands are recognized by ftp: 


! [command] [args] 


$ macro-name [args ] 


account [passwd] 


append local-file [remote-file] 


ascii 
bell 
binary 


bye 


case 


cd remote-directory 


cdup 


chmod mode file-name 


close 


cr 


delete remote-file 


Invoke an interactive shell on the local machine. If there are arguments, the first is 
taken to bea command to execute directly, with the rest of the arguments as its 
arguments. 

Execute the macro macro-name that was defined with the macdef command. 
Arguments are passed to the macro unglobbed. 

Supply a supplemental password required by a remote system for access to resources 
oncea login has bem successfully completed. If no argument is included, the user 
will be prompted for an account password in a nonechoing input mode 

Append a local file to a file on the remote machine. If remot e-file isleft unspecified, 
the local filename is used in naming the remote file after being altered by any ntrans 
or nmap setting. File transfer uses the current settings for type, format, mode, and 
structure 


Se the file transfer type to network ASCII. Thisisthe default type 
Arrange that a bell be sounded after each file transfer command is completed. 
Se the file transfer type to support binary image transfer. 


Terminate the FT P session with theremote server and exit ftp. An end of file will 
also terminate the session and exit. 

Toggle ranote computer filename case mapping during mget commands. W hen case 
is on (default is off), remote computer filenames with all letters in upper case are 
written in the local directory with the letters mapped to lowercase. 
Change the working directory on the remote machinetoremote-directory. 
Change the remote machine working directory to the parent of the current renote 
machine working directory. 

Change the permission modes of the filet i! e-name on the ranote system to mode. 
Terminate the FT P session with theremote serve, and return to the command 
interpreter. Any defined macros are erased. 

Toggle carriage return stripping during ASCII type file retrieval. Records are 
denoted by a carriage return/linefeed sequence during ASCII type file transfer. 
When cr ison (the default), carriage returns are stripped from this sequence to 
conform with the UNIX single linefeed record delimiter. Records on non-UN IX 
remote systems may contain single linefeeds; when an ASCII type transfer is made, 
these linefeeds may be distinguished from a record delimiter only when cr is off. 

D elete the filer emot e-file on the remote machine. 


debug [debug- value] 


dir [remote-directory] [local-file] 


disconnect 
form format 


get remote-file [local-file] 


glob 


hash 


help [command ] 


idle [seconds ] 


led [directory] 


1s [remote-directory] [local-file] 


macdef macro- name 


mdelete [remote-files ] 


Toggle debugging mode. If an optional debug- val ue is specified, it is used to set the 
debugging leva. W hen debugging is on, ftp prints each command sent to the 
remote machine, preceded by the string —>. 

Print alisting of the directory contentsin thedirectory, remote- directory, and, 
optionally, placing the output in| ocal- file. If interactive prompting is on, ftp will 
prompt the user to verify that the last argument is indeed the target local file for 
recaiving dir output. If no directory is specified, the current working directory on 
the renote machine is used. If no local file isspecified, or! ocal-file is-, output 
comes to the terminal. 

A synonym for close. 

Sé& the file transfer form to format. Thedefault format is file. 


Retrieve ther emot e-file and storeit on the local machine. If the local filename is 
not specified, it is given the same nameit has on the remote machine, subject to 
alteration by the current case, ntrans, and nmap settings. The current settings for 
type, form, mode, and structure are used while transferring thefile 

T oggle filename expansion for mdelete, mget, and mput. If globbing is turned off with 
glob, the filename arguments are taken literally and not expanded. Globbing for mput 
isdoneasin csh 1. For mdelete and mget, each remote filename is expanded 
separately on the remote machine and the lists are not merged. Expansion of a 
directory name is likely to be different from expansion of thename of an ordinary 
file: the exact result depends on the foraign operating system and FT P server, and 
can be previewed by doing mis renotefiles N ote: mget and mput are not meant to 
transfer entire directory subtrees of files. That can be done by transferring atar 1 
archive of the subtree (in binary mode). 

T oggle hash-sign (#) printing for each data block transferred. T he size of adata block 
is 1024 bytes. 

Print an informative message about the meaning of command. If no argument is given, 
ftp prints alist of the known commands. 


Se the inactivity timer on the remote server to seconds seconds. If seconds is 
omitted, the current inactivity timer is printed. 


Change the working directory on the local machine. If no directory is specified, the 
user’s home directory is used. 


Print a listing of the contents of a directory on the renote machine The listing 
includes any system-dependent information that the server chooses to include, for 
example, most systems will produce output from the command 1s 1. (See also 
nlist.) If remote- directory iSleft unspecified, the current working directory is used. 
If interactive prompting is on, ftp will prompt the user to verify that the last 
argument is indeed the target local file for receiving 1s output. If no local file is 
specified, or if! ocal-file is-, the output is sent to the teminal. 

D efine a macro. Subsequent lines are stored as the macro macro- name; anull line 
(consecutive newline characters in a file or carriage returns from the terminal) 
terminates macro input mode. There is a limit of 16 macros and 4096 total 
characters in all defined macros. M acros remain defined until aclose command is 
executed. The macro processor interprets $ and \ as special characters. A $ followed 
by anumber (or numbers) is replaced by the corresponding argument on the macro 
invocation command line A $ followed by an i signals that macro processor that the 
executing macro is to be looped. On the first pass $i is replaced by the first argument 
on the macro invocation command line on the second pass it is replaced by the 
second argument, and so on. A \ followed by any character is replaced by that 
character. Use the\ to prevent special treatment of thes. 


Delete theremote-files on therenote machine 
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mdir remote-files local-file 
mget remote-files 

mkdir directory-name 

mls remote-files local-file 


mode [mode- name ] 
modtime file-name 


mput |ocal-files 
newer file-name 


nlist [remote-directory] 
[local-file] 


nmap [inpattern] outpattern 


ntrans [inchars] [outchars ] 


Like dir, except multiple remote files may be specified. If interactive prompting is 
on, ftp will prompt the user to verify that the last argument is indeed the target local 
filefor reca ving mdir output. 


Expand theremote-files on the remote machine and do a get for each filename thus 
produced. See glob for details on the filename expansion. Resulting filevames will 
then be processed according to case, ntrans, and nmap settings. Files are transferred 
into the local working directory, which can be changed with 1ca directory ; new local 
directories can be created with !mkdir directory. 


M ake adirectory on the remote machine. 


Like nlist, except multiple remote files may be specified, and the 1ocal-file must 
be specified. If interactive prompting is on, ftp will prompt the user to verify that 
the last argument is indeed the target local file for reca ving mis output. 


Sé& the file transfer mode to mode- name. T he default mode is stream mode. 
Show the last modification time of the file on the remote machine. 


Expand wildcards in the list of local files given as arguments and do a put for each 
filein the resulting list. See giob for details of filename expansion. Resulting 
filenames will then be processed according to ntrans and nmap settings. 


Get the file only if the modification time of the remote file is more recent that the 
fileon the current system. If the file does not exist on the current system, the remote 
file is considered newer. O therwise, this command is identical to get. 


Print alist of the files in a directory on the remote machine. If remote- directory is 
left unspecified, the current working directory is used. If interactive prompting ison, 
p will prompt the user to verify that the last argument is indeed the target local file 
for recaving nlist output. If no local file is specified, or iflocal-file is-, the 
output is sent to theterminal. 


Se or unset the filename mapping mechanism. If no arguments are specified, the 
filename mapping mechanism is unset. If arguments are specified, renote filenames 
are mapped during mput commands and put commands issued without a specified 
remote target filename. If arguments are specified, local fileaames are mapped during 
mget commands and get commands issued without a specified local target filename. 
This command is useful when connecting to anon-UN1IX remote computer with 
different file naming conventions or practices. The mapping follows the pattern set 
by inpattern and outpattern. Inpattern isa template for incoming filevames (which 
may have already been processed according to thentrans and case settings). Variable 
templating is accomplished by including the sequences $1, $2,..., $9 iN inpattern. 
Use\ to prevent this special treatment of thes character. All other characters are 
treated literally, and are used to determine the nmap inpattern variable values. For 
example, given inpattern $1.$2 and the remote filename mydata.data, $1 would have 
the value mydata, and $2 would have the value "data". The outpattern determines the 
resulting mapped filename. T he sequences $1, $2,...., $9 are replaced by any value 
resulting from the inpattern template. The sequence $0 is replaced by the original 
filename. Additionally, the sequenceseqi, seq2 isreplaced byseqi ifseqi isnota 
null string; otherwise, it is replaced by seq2. For example the command nmap 
$1.$2.$3 [$1,$2].[$2,file] would yield the output filavame myfile.data for 
input filarames my-file. data and myfile.data.old, myfile.file for the input 
filename my-file, and myfile.myfile for theinput filename .myfile. Spaces may be 
included in outpattern, asin the example: nmap $1 sed "s/ *$//" > $1. Usethe \ 
character to prevent special treatment of thes, [, [, and , characters. 

Se or unset the filename character translation mechanism. If no arguments are 
specified, the filename character translation mechanism is unset. If arguments are 
specified, characters in remote filenames are translated during mput commands and 
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open host [port ] 


prompt 


proxy ftp-command 


put local-file [remote-file] 


pwd 

quit 

quote argl arg2... 

recv remote-file [local-file] 


reget remote-file [local-file] 


remotehelp [command- name ] 
remotestatus [fil e-name] 
rename [from] [to] 


reset 


restart marker 


* 


put commands issued without a specified remote target filename. If arguments are 
specified, characters in local filenames are translated during mget commands and get 
commands issued without a specified local target filerame. T his command is useful 
when connecting to anon-UNIX remote computer with different file naming 
conventions or practices. Characters in a filename matching a character ini nchars 
are replaced with the corresponding character in out chars. If the character’s position 
ininchars islonger than the length of out chars, the character is ddeted from the 
filename. 

Establish a connection to the specified host FTP server. An optional port number 
may be supplied, in which case, ftp will attempt to contact an FTP server at that 
port. If the auto-1login option is on (default), ftp will also attempt to automatically 
log the user in to the FT P server (see bdow). 

T oggle interactive prompting. Interactive prompting occurs during multiple file 
transfers to allow the user to selectively retrieve or store files. If prompting is turned 
off (default ison), any mget or mput will transfer all files, and any mdelete will delete 
all files. 

Execute an ftp command on a secondary control connection. This command allows 
simultaneous connection to two renoteFT P servers for transferring files between 
the two servers. T he first proxy command should be an open, to establish the 
secondary control connection. Enter the command "proxy 2" to see other ftp 
commands executable on the secondary connection. T he following commands 
behave differently when prefaced by proxy :, open will not define new macros during 
the auto-login process, close will not erase existing macro definitions, get and mget 
transfer files from the host on the primary control connection to the host on the 
secondary control connection, and put, mput, and append transfer files from the host 
on the secondary control connection to the host on the primary control connection. 
Third-party file transfers depend upon support of the FT P protocol pasv command 
by the server on the secondary control connection. 

Store a local file on the ranote machine If remote-file isleft unspecified, the local 
filename is used after processing according to any ntrans Or nmap settings in naming 
the remote file File transfer uses the current settings for type, format, mode, and 
structure. 

Print the name of the current working directory on the remote machine. 

A synonym for bye. 

The arguments specified are sent, verbatim, to the renoteFT P server. 

A synonym for get. 

Reget acts like get, except that if! ocal-file exists and issmaller than remote-file, 
local-file iSpresumed to bea partially transferred copy of remot e-file andthe 
transfer is continued from the apparent point of failure. This command is useful 
when transferring very large files over networks that are prone to dropping 
connections. 

Request hdp from the remote FT P server. If acommand- name is specified, it is supplied 
to the server as well. 

With no arguments, show status of renote machine. If fi! e-name is specified, show 
status of fi | e-name on remote machine 

Rename the file from on the renote machine, to thefileto. 

Clear reply queue. This command resynchronizes command/reply sequencing with 
the remote FT P server. Resynchronization may be necessary following a violation of 
the FTP protocol by the remote server. 


Restart theimmediatdy following get or put at the indicated marker. On UNIX 
systems, marker iS usually a byte offset into the file. 
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rmdir directory-name 


runique 


send local-file [remote-file] 


sendport 


site argl arg2... 


size file-name 
status 
struct [struct-name ] 


sunique 


system 
tenex 
trace 


type [type-name ] 
umask [newmask ] 


user user-name [password] [account ] 


verbose 


2? [command ] 


D elete a directory on the renote machine. 

T oggle storing of fileson thelocal system with unique filenames. If a file already 
exists with a name equal to the target local filename for a get or mget Command, a .1 
is appended to thename. If the resulting name matches another existing file, a .2 is 
appended to the original name. If this process continues up to .99, an error message 
is printed, and thetransfer does not take place. The generated unique filename will 
be reported. N ote that runique will not affect local files generated from a shall 
command. T he default value is off. 

A synonym for put. 

T oggle the use of port commands. By default, ftp will attempt to use a porT 
command when establishing a connection for each data transfer. T he use of Port 
commands can prevent delays when performing multiple file transfers. If the port 
command fails, ftp will use the default data port. W hen the use of port commands is 
disabled, no attenpt will be made to use port commands for each data transfer. T his 
is useful for certain FT P implementations which do ignore port commands but, 
incorrectly, indicate they've been accepted. 

The arguments specified are sent, verbatim, to the ranote FT P server as a SITE 
command. 

Return size of file-name on ranote machine 

Show the current status of ftp. 

Se the file transfer structure to st ruct-name. By default stream structure is used. 

T oggle storing of files on renote machine under unique filenames. Remote FT P 
server must support ftp protocol stou command for successful completion. The 
remote server will reoort unique name D efault value is off. 

Show the type of operating system running on the remote machine 

Se the file transfer type to that needed to talk to TEN EX machines. 

T oggle packet tracing. 

Se the file transfer type to type- name. If no type is specified, the current type is 
printed. T he default type is network ascrt. 

Sé& the default umask on the renote server to newmask. If newmask isomitted, the 
Current umask is printed. 

Identify yourself to the renote FT P server. If the password is not specified and the 
server requiresit, #tp will prompt the user for it (after disabling local echo). If an 
account fied is not specified, and the FT P server requires it, the user will be 
prompted for it. If an account fied is specified, an account command will be relayed 
to the remote server after the login sequence is completed if the remote server did 
not require it for logging in. Unless ftp isinvoked with auto-login disabled, this 
process is done automatically on initial connection to the FT P server. 

T oggle verbose mode. In verbose mode, all responses from the FT P server are 
displayed to the user. In addition, if verbose is on, when a file transfer completes, 
statistics regarding the efficiency of the transfer are reported. By default, verbose is 
on. 

A synonym for help. 


Command arguments which have enbedded spaces may be quoted with quotation marks (“). 


ABORTING A FILE TRANSFER 


To abort a file transfer, use the terminal interrupt key (usually Ctrl-C). Sending transfers will be immediately halted. 
Receiving transfers will be halted by sending an FT P protocol asor command to the renote server, and discarding any 
further data recaved. T he speed at which this is accomplished depends upon the remote server's support for aBor processing. 


= 


If the remote server does not support the asor command, an ftp> prompt will not appear until the remote server has 
completed sending the requested file. 

Theterminal interrupt key sequence will be ignored when ftp has completed any local processing and is awaiting a reply 
from the renote server. A long delay in this mode may result from the aBor processing described earlier in this section, or 
from unexpected behavior by the remote server, including violations of the FTP protocol. If the delay results from unex- 
pected remote server behavior, the local ftp program must be killed by hand. 


FILENAMING CONVENTIONS 
Files specified as arguments to ftp commands are processed according to the following rules: 
If the filarame - is specified, the stain (for reading) or stdout (for writing) is used. 


If the first character of the filename isj, the renainder of the argument is interpreted as a shell command. ftp then forks a 
shell, using popen 3 with the argument supplied, and reads (writes) from the stdout (stdin). If the shell command includes 
spaces, the argument must be quoted; for example, 1s -1t. A particularly useful example of this mechanism is: dir more. 


Failing the preceding checks, if “globbing” is enabled, local filenames are expanded according to the rules used in thecsh 1; 
c.f. the glob command. If the ftp command expects a single local file (for example, put), only the first filename generated by 
the “globbing” operation is used. 


For mget Commands and get commands with unspecified local filenames, the local filerame is the remote filename which 
may be altered by acase, ntrans, OF nmap setting. T he resulting filename may then be altered if runique ison. 





For mput commands and put commands with unspecified remote filenames, the renote filename is the local filename, which 
may be altered by an ntrans or nmap setting. The resulting filename may then be altered by the remote server if sunique is on. 


FILE TRANSFER PARAMETERS 


The FTP specification specifies many parameters that may affect a file transfer. The type may be one of ASCII, image 
(binary), ebcdic, and local byte size (for PD P N s-10s and PDP Ns-20s mostly). #tp supports the ASCII and image types of 
file transfer, plus local byte size 8 for tenex mode transfers. 


ftp supports only the default values for the remaining file transfer parameters: mode, form, and struct. 


THE .netrc FILE 


The file contains login and initialization information used by the auto-login process. It resides in the user’s home directory. 
The following tokens are recognized; they may be separated by spaces, tabs, or newlines: 


machine name Identify a remote machine name The auto-login process searches the file for a machine token that 
matches the renote machine specified on the ftp command line or as an open command argument. 
When a match is made, the subsequent tokens are processed, stopping when the end of file is 
reached or another machine or a default token is encountered. 

default This is the same as machine name except that default matches any name. There can be only one 
default token, and it must be after all machine tokens. This is normally used asdefault |ogin 
anonymous password user @site, thereby giving the user automatic anonymous ftp login to machines 
not specified. T his can be overridden by using the -n flag to disable auto-login. 





login name Identify a user on the renote machine. If this token is present, the auto-login process will initiate a 
login using the specified name 
password string Supply a password. If this token is present, the auto-login process will supply the specified string if 


the remote server requires a password as part of the login process. N ote that if this token is present 
in the file for any user other than anonymous, ftp will abort the auto-login process if the is readable 
by anyone besides the user. 

account string Supply an additional account password. If this token is present, the auto-login process will supply 
the specified string if the ranote server requires an additional account password, or the auto-login 
process will initiate an acct command if it does not. 
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macdef name D efine a macro. This token functions like the ftp macdef command functions. A macro is defined 
with the specified name its contents begin with the next line and continue until a null line 
(consecutive newline characters) is encountered. If a macro named init is defined, it is automati- 
cally executed as the last step in the auto-login process. 
ENVIRONMENT 
ftp utilizes the following environment variables: 


HOME For default location of a file, if one exists 
SHELL For default shal 


SEE ALSO 


ftpd(8) 


HISTORY 
The ftp command appeared in BSD 4.2. 


BUGS 
Correct execution of many commands depends upon proper behavior by the remote server. 


An error in thetreatment of carriage returnsin the BSD 4.2 ASCII-mode transfer code has been corrected. This correction 
may result in incorrect transfers of binary files to and from BSD 4.2 servers using the ASCI| type. Avoid this problen by 
using the binary image type. 


BSD 4.2, 30 July 1991 


fuser 





user— Identify processes using files 
SYNOPSIS 
user [-a}-s][-signal ][-kmuv] filename ... [-][-signal ][-kmuv] filename ... 
user [-1] 
DESCRIPTION 
user displays the PID s of processes using the specified files or file systems. In the default display mode, each filename is 


followed by a letter denoting the type of access: 


c Current directory. 

e Executable being run. 

f Open file + is omitted in default display mode 
r Root directory. 

m mmap’ed file or shared library. 


fuser returns anonzero return code if none of the specified files is accessed or in case of a fatal error. If at least one access has 
been found, fuser returns zero. 


OPTIONS 
-a Show all files specified on the command line By default, only files that are accessed by at least one process 
are shown. 
-k Kill processes accessing the file Unless changed with -signal, s1GkILL issent. A fuser process never kills 


itself, but may kill other fuser processes. 


u List all known signal names. 


=m filename specifies a file on amounted file system or a block device that is mounted. All processes accessing 
files on that file system are listed. If a directory fileis specified, it is automatically changed to filename/. to 
use any file system that might be mounted on that directory. 


-s Silent operation. -a, -u, and -v are ignored in this mode. 

-signal Use the specified signal instead of stak1LL when killing processes. Signals can be specified ather by name 
(for example, -HuP) or by number (for example, -1). 

-u Append the username of the process owner to each PID. 

-v Verbose mode. Processes are shown in aps-like style. The fidds p1p, user, and commanp are similar to ps. 


Access shows how the process accesses the file. 
- Reset all options and set the signal back to s1GKILL. 


FILES 


/proc Location of the proc file system 


EXAMPLES 


fuser -km /home Kills all processes accessing the file system /home in any way. 
In this example: 
if fuser -s /dev/ttyS1; then :; else something 


fi invokes something if no other process is using /dev/ttyS1. 


RESTRICTIONS 


Processes accessing the same file or filesystem several times in the same way are only shown once 


AUTHOR 


Werner Almesberger (<almesber@di.epf1.ch>U) 


SEE ALSO 


kill(1), killal1(1), ps(1), ki11(2) 
Linux, 11 October 1994 


gt+ 
g++—GNU project C++ Compiler 
SYNOPSIS 
gt+ [ option | filename ]. .. 
DESCRIPTION 


TheC and C++compilers are integrated; g++ isascript to call gcc with options to recognize C ++. gcc processes input files 
through one or more of four stages: preprocessing, compilation, assembly, and linking. This man page contains full 
descriptions for only C ++ specific aspects of the compiler, though it also contains summaries of some general-purpose 
options. For a fuller explanation of the compiler, see gec(1). 


C ++ source files use one of the suffixes .c, .cc, .cxx, .cpp, OF .c++; preprocessed C ++ files use the suffix .ii. 


OPTIONS 


There are many command-line options, including options to control details of optimization, warnings, and code generation, 
which are common to both gcc and g++. For full information on all options, see gec(1). 
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O ptions must be separate -ar is quite different from -a -r. 


M ost -f and -w options have two contrary forms: -fname and -fno-name (Or -Wname and -wno-name). O nly the nondefault 


forms are shown here. 


-c 


-Dmacro 
-Dmacro=defn 
-E 


-fall-virtual 


-fdollars-in-identifiers 


-felide-constructors 


-fenum-int-equiv 


-fexternal-templates 


-fno-gnu-linker 


-fmemoize-lookups-fsave-memorized 


Compile or assemble the source files, but do not link. The compiler output isan 
object file corresponding to each source file. 


Define macro macro with the string 1 asits definition. 

Define macro macro aSdefn. 

Stop after the preprocessing stage; do not run the compiler proper. The output is 
preprocessed source code, which is sent to the standard output. 

T reat all possible menber functions as virtual, implicitly. All member functions 
(except for constructor functions and new or ddete member operators) are treated as 
virtual functions of the class where they appear. 


This does not mean that all callsto these member functions will be made through 
the internal table of virtual functions. Under some circumstances, the compiler can 
determine that a call to a given virtual function can be made directly; in these cases 
the calls are direct in any case. 


Permit the use of $ in identifiers. Traditional C allowed the character $ to form part 
of identifiers; by default, GNU C also allows this. H owever, AN SI C forbids $ in 
identifiers, and GNU C +talso forbids it by default on most platforms (though on 
some platforms it’s enabled by default for GNU C ++as well). 


Use this option to instruct the compiler to be smarter about when it can dide 
constructors. Without this flag, GNU C-++and cfront both generate effectively the 
same code for 

A foo ()3 

A x (foo ()); // x initialized by ‘foo ()', no ctor called 

A y = foo (); // call to 'foo ()' heads to temporary, // y is initial- 
ized from the temporary. 

N ote the difference. With this flag, GNU C++initializesy directly from the call to 
foo() without going through a temporary. 

Normally GNU C ++allows conversion of enum to int, but not the other way 
around. Use this option if you want GN U C ++ to allow conversion of int to enum as 
well. 


Produce smaller code for tenplate declarations, by generating only asingle copy of 
each template function where it is defined. To use this option successfully, you must 
also mark all files that use templates with either #pragma implementation (the 
definition) or #pragma interface (declarations). 

When your code is compiled with -fexternal-templates, all tanplate instantiations 
are external. You must arrange for all necessary instantiations to appear in the 
implenentation file you can do this with a typedet that references each instantiation 
needed. Conversely, when you compile using the default option -fno- external- 
templates, all template instantiations are explicitly internal. 

Do not output global initializations (such as C ++ constructors and destructors) in 
the form used by the GNU linker (on systens where the GN U linker is the standard 
method of handling then). Use this option when you want to useanon-GN U 
linker, which also requires using the collect2 program to make sure the systen 
linker includes constructors and destructors. (collect2 isincluded in theGNU CC 
distribution.) For systems which must use collect2, the compiler driver gcc is 
configured to do this automatically. 

T hese flags are used to get the compiler to compile programs faster using heuristics. 
They are not on by default since they are only effective about half the time The 
othe half of the time programs compile more slowly (and take more memory). 


-fno-default-inline 


-fno-strict-prototype 


-fhandle-signatures- 
fno-handle-signatures 


-fthis-is-variable 
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The first time the compiler must build a call to amember function (or reference to a 
data menber), it must (1) determine whether the class implements menber 
functions of that name (2) resolve which member function to call (which involves 
figuring out what sorts of type conversions need to be made); and (3) check the 
visibility of the member function to the caller. All of this adds up to slower 
compilation. N ormally, the second time a call is made to that member function (or 
reference to that datamembe), it must go through the same lengthy process again. 
This means that code like this: 

cout << "This " << p << "has"<< n << " legs.\n"; 

makes six passes through all three steps. By using a software cache, a “hit” signifi- 
cantly reduces this cost. U nfortunately, using the cache introduces another layer of 
mechanisms which must be implemented, and so incurs its own overhead. - 
fmemorize- lookups @Mables the software cache. 

Because access privileges (visibility) to manbers and member functions may differ 
from one function context to the next, g++ may need to flush the cache With the - 
fmemoize-lookups flag, the cache is flushed after every function that is compiled. The 
-fsave-memorized flag enables the same software cache, but when the compiler 
determines that the context of the last function compiled would yield the same 
access privileges of the next function to compile, it preserves the cache This is most 
hapful when defining many member functions for the same class: with the 
exception of member functions which are friends of other classes, each member 
function has exactly the same access privileges as every other, and the cache need not 
be flushed. 

Do not make member functions inline by default merely because they are defined 
inside the class scope. O therwise, when you specify -o, member functions defined 
inside class scope are compiled inline by default; that is, you don’t need to add 
inline in front of the member function name 

Consider the declaration int foo;().1n C +4, this means that the function foo takes 
no arguments. In ANSI C, this is declared int foo(void) ;. With the flag -fno- 
strict-prototype, declaring functions with no arguments is equivalent to declaring 
its argument list to be untyped, thatis, int foo(); is equivalent to saying int foo 
(...)j.-fnonnull-objects. Normally, GNU C +4+makes conservative assumptions 
about objects reached through references. For example the compiler must check that 
aisnot null in code like the following: 

obj &a = g (); 

a.f (2); 

Checking that references of this sort have non-null values requires extra code, 
however, and it is unnecessary for many programs. You Can use -fnonnull-objects to 
omit the checks for null, if your program doesn’t require the default checking. 

T hese options control the recognition of the signature and sigof constructs for 
specifying abstract types. By default, these constructs are not recognized. 

The incorporation of user-defined free store managenent into C ++has made 
assignment to this an anachronism. Therefore, by default GNU C++ treats the type 
of thisin amember function of class X to bex *const. In other words, it is illegal to 
assign to this within aclass member function. H owever, for backwards compatibil- 
ity, you can invoke the old behavior by using -fthis-is-variable. 

Produce debugging information in the operating system's native format (for D BX or 
SDB or DWARF). GDB also can work with this debugging information. On most 
systems that use D BX format, -g enables use of extra debugging information that 
only GDB can use 

Unlike most other C compilers, GNU CC allows you to use -g with -o. The 
shortcuts taken by optimized code may occasionally produce surprising results: some 
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-Idir 
-Ldir 
-lii brary 


-nostdinc 


-nostdinct+ 


-traditional 


-Umacro 
-Wall 


-Wenum-clash 
-Woverloaded-virtual 


variables you declared may not exist at all; flow of control may briefly move where 
you did not expect it; some statements may not be executed because they compute 
constant results or ther values were already at hand; some statements may execute in 
different places because they were moved out of loops. 

N everthdless, it proves possible to debug optimized output. This makes it reasonable 
to use the optimizer for programs that might have bugs. 

Append directory dir to the list of directories searched for include files. 

Add directory dir to thelist of directories to be searched for -1. 

Use the library named |i brary when linking. (C++ programs often require -19++ for 
successful linking.) 

Do not search the standard system directories for header files. O nly the directories 
you have specified with -1 options (and the current directory, if appropriate) are 
searched. 

Do not search for header files in the standard directories specific to C-H, but do still 
search the other standard directories. (T his option is used when building 1ibg++.) 
Optimize Optimizing compilation takes somewhat moretime, and alot more 
memory for a large function. 

Place output in filefile. 

Stop after the stage of compilation proper; do not assemble. T he output is an 
assembler code file for each nonassembler input file specified. 

Attempt to support some aspects of traditional C compilers. Specifically, for both C 
and C ++ programs: 

In the preprocessor, comments convert to nothing at all, rather than to a space. T his 
allows traditional token concatenation. 

In the preprocessor, macro arguments are recognized within string constants in a 
macro definition (and thar values are stringified, though without additional quote 
marks, when they appear in such a context). T he preprocessor always considers a 
string constant to end at anewline 

The preprocessor does not predefine the macro stoc when you use -traditional, but 
still predefines anuc (sincethe GN U extensionsindicated by enuc are not affected by 
raditional).|1f you need to write header files that work differently depending on 
whether -traditional isin use, by testing both of these predefined macros you can 
distinguish four situations: GNU C, traditional GNU C, othe AN SI C compilers, 
and other old C compilers. 

In the preprocessor, comments convert to nothing at all, rather than to a space. T his 
allows traditional token concatenation. 

String “constants” are not necessarily constant; they are stored in writable space, and 
identical looking constants are allocated separately. For C ++ programs only (not C), 
-traditional has one additional effect: assignment to this is permitted. Thisis the 
same as the effect of -fthis-is-variable. 

Undefine macro macro. 
Issue warnings for conditions that pertain to usage that we recommend avoiding and 
that we believe is easy to avoid, even in conjunction with macros. 

Warn when convetting between different enumeration types. 

In a derived class, the definitions of virtual functions must match the type signature 
of a virtual function declared in the base class. U se this option to request warnings 
when a derived class declares a function that may bean erroneous attempt to define 
a virtual function; that is, warn when a function with thesame name asa virtual 
function in the base class, but with a type signature that doesn’t match any virtual 
functions from the base class. 








-Wtemplate-debugging When using templates in aC -++ program, warn if debugging is not yet fully 
available. 
-w Inhibit all warning messages. 
+eN Control how virtual function definitions are used, in a fashion compatible with 
cfront 1.x. 
PRAGMAS 


Two #pragma directives are supported for GNU CH, to permit using the same header file for two purposes: as a definition of 
interfaces to a given object class, and as the full definition of the contents of that object class. 


#pragma interface Use this directive in header files that define object classes, to save space in most of 
the object files that use those classes. N ormally, local copies of certain information 
(backup copies of inline member functions, debugging information, and the internal 
tables that implement virtual functions) must be kept in each object file that 
includes class definitions. You can use this pragma to avoid such duplication. When 
a header file containing #pragma interface iSincluded in a compilation, this auxiliary 
information will not be generated (unless the main input source file itself uses 
#pragma implementation). Instead, the object files will contain references to be 
resolved at link time 

#pragma implementation Use this pragmain a main input file when you want full output from included 

#pragma implementation !objects.h! header files to be generated (and made globally visible). T he included header file, in 
turn, should use #pragma interface. Backup copies of inline membe functions, 
debugging information, and the internal tables used to implement virtual functions 
are all generated in implementation files. 
If you use #oragma implementation with no argument, it applies to an include file 
with the same basename as your source file; for example, in allclass.cc, #pragma 
implementation by itsef is equivalent to #pragma implementation "allclass.h". Use 
the string argument if you want a single implementation file to include code from 
multiple header files. 
Thereis no way to split up the contents of a single header fileinto multiple 
implementation files. 








FILES 
ile.h C header (preprocessor) file 
ile.i Preprocessed C source 
ile file.c C ++ source file 
ile.cc C ++ source file 
ile.cxx C++ source file 
ile.s Assembly language file 
ile.o O bject file 
a.out Link edited output 
TMPDIR/cc Temporary files 
LIBDIR/cpp Preprocessor 
LIBDIR/cciplus Compiler 
LIBDIR/collect Linker front end needed on some machines 
LIBDIR/libgcc.a GCC subroutine library 
/lib/crt[1n].o Start-up routine 
LIBDIR/ccrt® Additional start-up routine for C ++ 


/lib/libe.a Standard C library; see intro(3) 
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/usr/include Standard directory for #include files 
LIBDIR/ include Standard gcc directory for #include files 
LIBDIR/g++-include Additional g++ directory for #include 


LIBDIR is usually /usr/local/lib/machine/version. 
TMPDIR Comes from the environment variable Tupp1R (default /usr/tmp if available else /tmp). 


SEE ALSO 
gec(1), cpp(1), as(1), 14(1), gdb(1), adb(1), dbx(1), sdb(1), gcc, cpp, as, 1d, ANd gdb entriesin info. 
Usngand PortingGNU CC (for version 2.0), Richard M . Stallman; TheC Preprocesor, Richard M . Stallman; D ebugging 
with GDB: theGNU Source Levd D ebugge,, Richard M. Stallman and Roland H. Pesch; Usngas theGNU Assembler, D ean 
Elsner, J ay Fenlason and friends; gid: the GNU linker, Steve Chamberlain and Roland Pesch. 


BUGS 


For instructions on how to report bugs, seethe GCC manual. 


COPYING 


Copyright © 1991, 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim 
copies of this manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


AUTHORS 
See the GN U CC M anual for the contributorsto GNU CC. 
GNU Tools, 30 April 1993 
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g3topbm— Convert aG roup 3 fax file into a portable bitmap 


SYNOPSIS 
g3topbm [-kludge][-reversebits][-stretch][g3file] 
DESCRIPTION 
Reads a Group 3 fax file as input. Produces a portable bitmap as output. 
OPTIONS 
-kludge T ells g3topbm to ignore the first few lines of the file; sometimes fax files have some junk at the beginning. 


-reversebits T alls g3topbm to interpret bits least-significant first, instead of thedefault most-significant first. 
Apparently, some fax modems do it one way and others do it the other way. If you get a whole bunch of 
“bad code word” messages, try using this flag. 

-stretch Tells g3topbm to stretch the image vettically by duplicating each row. This is for the low-quality transmis- 
sion mode. 





All flags can be abbreviated to their shortest unique prefix. 


REFERENCES 
The standard for Group 3 fax is defined in CCITT Recommendation T.4. 


BUGS 
Probably. 


SEE ALSO 


pbmtog3(1), pbm(5) 


AUTHOR 
Copyright © 1989 by Paul H aeberli (paulemanray.sgi.com) 
2 October 1989 
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gawk— Pattern scanning and processing language 


SYNOPSIS 
gawk [ POSIX or GNU style options ] -f program-file [ -- ] file ... 
gawk [ POSIX or GNU style options ] [ -- ] program-text file... 
DESCRIPTION 


gawk isthe GNU Project's implementation of the awk programming language It conforms to the definition of the language 
in the 1003.2 Command Language and Utilities Standard. T his version in turn is based on the description in The AWK 
Programming Language, by Aho, Kernighan, and W einberge, with the additional features defined in the System V Rdease 4 
version of awk. gawk also provides some GN U -specific extensions. 


The command line consists of options to gawk itsdf, the awk program text (if not supplied via the-# or --file options), and 
values to be made available in the arcc and arev predefined awk variables. 


OPTIONS 


gawk options may be athe the traditional one letter options, or the GN U-style long options. Traditional style options start 
with a single -, whileGN U long options start with --. GN U-style long options are provided for both GN U -specific features 
and for mandated features. O ther implementations of the awk language are likely to only accept the traditional one letter 
options. 

Following the standard, gawk-specific options are supplied via arguments to the -w option. M ultiple -w options may be 
supplied, or multiple arguments may be supplied together if they are separated by commas, or enclosed in quotes and 
separated by whitespace C aseis ignored in arguments to the -w option. Each -w option has a corresponding GN U-style long 
option, as detailed below. Arguments to GN U-style long options are athe joined with the option by an = sign, with no 
intervening spaces, or they may be provided in the next command-line argument. 


gawk accepts the following options: 


-F fs, --field-separator=fs Usets for theinput field separator (the value of the Fs-predefined variable). 


-v var=val, --assign=var=val | Assign thevalueval , to the variablevar , before execution of the program begins. Such 
variable values are available to the Bea1n block of an awk program. 


-f program file, Read the awk program source from the file program- file, instead of from the first 
--file=programfile command-line argument. M ultiple -+ (or --file) options may be used. 
-mf=NNN, -mr=NNN Sé various memory limits to the value nnn. The t flag sets the maximum number of fields, 


and the r flag sets the maximum record size T hese two flags and the -m option arefrom the 
AT&T Bell Labs research version of awk. T hey are ignored by gawk, since gawk has no 
predefined limits. 
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-W compat, --compat Run in compatibility mode In compatibility mode, gawk behaves identically to awk; none of 
the GN U-specific extensions are recognized. See “GNU Extensions,” later in this manual 
page, for more information. 


-W copyleft, -W copyright, Print the short version of the GN U copyright information message on the error output. 

--copyleft, --copyright 

-W help, -W usage Print ardativey short summary of the available options on the error output. Per the GN U 

--help, --usage Coding Standards, these options cause an immediate successful exit. 

-W lint, --lint Provide warnings about constructs that are dubious or nonportable to other awk implenen- 
tations. 

-W posix, --posix This turns on compatibility mode, with the following additional restrictions:\x escape 


sequences are not recognized. 
Thesynonym func for the keyword function is not recognized. 
The operators ** and **= cannot be used in place of * and *=. 


-W source=program-text, Useprogram-text aS awk program source code This option allows the easy intermixing of 

--source=program- text library functions (used via the -f and --file options) with source code entered on the 
command line. It is intended primarily for medium to large awk programs used in shell 
scripts. 


The -w source= form of this option uses the rest of the command-line argument for 
program-text ; no other options to -w will be recognized in the same argument. 

-W version, --version Print version information for this particular copy of gawk on the error output. T his is useful 
mainly for knowing if the current copy of gawk on your system is up-to-date with respect to 
whatever the Free Software Foundation is distributing. Pe: the GNU Coding Standards, 
these options cause an immediate, successful exit. 

-- Signal the end of options. T his is useful to allow further arguments to the awk program itself 
to start with a-. This is mainly for consistency with the argument-parsing convention used 
by most other programs. 


In compatibility mode, any other options are flagged as illegal, but are otherwise ignored. In normal operation, aslong as 
program text has been supplied, unknown options are passed on to the awk program in the arev array for processing. T his is 
particularly useful for running awk programs via the #: executable interpreter mechanism. 


awk PROGRAM EXECUTION 
An awk program consists of a sequence of pattern-action statements and optional function definitions: 


pattern { action statements } 
function name (parameter list) { statements } 


gawk first reads the program source from the program-file(s) if specified, from arguments to -w source=, or from the first 
nonoption argument on the command line The -+ and -w source= options may be used multiple times on the command 
line. gawk will read the program text as if all the program-files and command-line source texts had been concatenated 
together. This is useful for building libraries of awk functions, without having to include them in each new awk program that 
uses them. It also provides the ability to mix library functions with command-line programs. 


The environment variable awKPaTH specifies a search path to use when finding source files named with the -+ option. If this 
variable does not exist, the default path is .:/usr/1lib/awk: /usr/local/1ib/awk. 


If a filename given to the -f option contains a/ character, no path search is performed. 


gawk executes awk programs in the following orde.. First, all variable assignments specified via the -v option are performed. 
N ext, gawk compiles the program into an internal form. Then, gawk executes the code in the Beain block(s) (if any), and then 
proceeds to read each filenamed in the arev array. If there are no files named on the command line, gawk reads the standard 
input. 


If a filename on the command line has the form var =val , it is treated as a variable assignment. The variablevar will be 
assigned the value val . (This happens after any BeaIn block(s) have been run.) Command-line variable assignment is most 


useful for dynamically assigning values to the variables awk uses to control how input is broken into fields and records. It is 
also useful for controlling state if multiple passes are needed over a single data file 


If the value of a particular denent of arev isempty (""), gawk Skips over it. 


For each line in the input, gawk tests to see if it matches any pattern in the awk program. For each pattern that the line 
matches, the associated action is executed. The patterns are tested in the order they occur in the program. 


Finally, after all the input is exhausted, gawk executes the code in the eno block(s) (if any). 


VARIABLES AND FIELDS 


awk variables are dynamic; they come into existence when they are first used. T heir values are ether floating-point numbers 
or strings, or both, deoending upon how they are used. awk also has one-dimensiona arrays; arrays with multiple dimensions 
may be simulated. Several predefined variables are set as aprogram runs, these will be described as needed and summarized 
in the “Built-In Variables’ subsection. 


FIELDS 


Aseach input line is read, gawk splits the line into fields, using the value of the Fs variable as the field separator. If Fs isa 
single character, fields are separated by that character. O therwise, rs is expected to bea full regular expression. In the special 
case that Fs is a single blank, fidds are separated by runs of blanks or tabs. N ote that the value of 1cnorecaseE (see the 
following) will also affect how fidds are split when Fs is a regular expression. 


If the FIELDWIDTHS variable is set to a space separated list of numbers, each fidd is expected to have fixed width, and gawk will 
split up the record using the specified widths. The value of Fs is ignored. Assigning anew value to Fs overrides the use of 
FIELDWIDTHS, and restores the default behavior. 

Each fidd in the input line may be referenced by its position, $1, $2, and so on. $0 isthewholeline T he value of afield may 
be assigned to as well. Fiddds need not be referenced by constants: 

n =5 

print $n 

prints the fifth field in theinput line T he variable nr is set to the total number of fiddsin theinput line 

References to nonexistent fields (that is, fields after snr) produce the null-string. H owever, assigning to a nonexistent fidd 
(for example, $(NF+2) = 5) will increase the value of nr, create any intervening fidds with the null string as their value, and 


cause the value of $0 to be recomputed, with the fidds being separated by the value of ors. References to negative numbered 
fidds cause a fatal error. 


BUILT-IN VARIABLES 
awk’s built-in variables are the following: 


ARGC Thenumber of command-line arguments (does not include options to gawk, or the program source). 

ARGIND The index in arev of the current file being processed. 

ARGV Array of command-line arguments. T he array is indexed from @ to arcc - 1. Dynamically changing the 
contents of arev can control the files used for data. 

CONVEMT The conversion format for numbers, “%.6g”, by default. 

ENVIRON An array containing the values of the current environment. The array is indexed by the environment 


variables, each element being the value of that variable (for example, ENVIRON, "HOME"] might be /u/arnold). 
Changing this array does not affect the environment seen by programs which gawk spawns via redirection 
or the system() function. (This may change in a future version of gawk.) 

ERRNO If a system error occurs either doing a redirection for getline, during aread for getline, or duringa 
close(), then errno will contain a string describing the error. 

FIELDWIDTHS A whitespace separated list of fiddwidths. When set, gawk parses the input into fields of fixed width, 
instead of using the value of the Fs variable as the field separator. T he fixed field width facility is still 
experimental; expect the semantics to change as gawk evolves over time. 
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FILENAME Thename of the current input file If no files are specified on the command line, the value of FILENAME is -. 
H owever, FILENAME iS undefined inside the Bearn block. 

FNR The input record number in the current input file 

FS The input fidd separator, a blank by default. 

IGNORECASE Controls the case-sensitivity of all regular expression operations. If tanorecase has anonzero value, then 


pattern matching in rules, fidd splitting with Fs, regular expression matching with ~ and !~, and the 
gsub( ), index( ), match( ), sp1it( ),and sub( ) predefined functionswill all ignore case when doing regular 
expression operations. T hus, if 1gNoRECASE is not equal to zero, /aB/ matches all of the strings ab, aB, Ab, 
and as. As with all awk variables, the initial value of 1GNorEcAsE is zero, so all regular expression operations 
are normally case-sensitive. 


NF The number of fidds in the current input record. 

NR The total number of input records seen so far. 

OFMT The output format for numbers, "%.6g", by default. 

OFS The output field separator, a blank by default. 

ORS The output record separator, by default a newline. 

RS Theinput record separator, by default anewline. rs is exceptional in that only the first character of its 


string value is used for separating records. (T his will probably change in a future release of gawk.) If Rs is set 
to the null string, then records are separated by blank lines. W hen rs is set to the null string, then the 
newline character always acts as a fidd separator, in addition to whatever value Fs may have. 


RSTART The index of the first character matched by match(); @ if no match. 

RLENGTH Thelength of the string matched by match(); -1 if no match. 

SUBSEP The character used to separate multiple subscripts in array dements, by default ne34. 
ARRAYS 


Arrays are subscripted with an expression between square brackets. If the expression is an expression list (expr, expr ...) 
then the array subscript is a string consisting of the concatenation of the (string) value of each expression, separated by the 
value of the sussep variable. T his facility is used to simulate multiply dimensioned arrays. For example, 


i= AY j= BY k=" 
x[i, j, k] = "hello, world\n" 

assigns the string hello, world\n to the element of the array x which is indexed by the string "a\o34B\034c". All arraysin awk 
are associative, that is indexed by string values. 


The special operator in may be used in an if Or while statement to see if an array has an index consisting of a particular 
value: 


if (val in array) 
print array[val] 


If the array has multiple subscripts, use (i,j)in array. 
The in construct may also be used in a for loop to iterate over all the elements of an array. 


An element may be deleted from an array using the delete statement. The delete statement may also be used to delete the 
entire contents of an array. 


VARIABLE TYPING AND CONVERSION 


Variables and fidds may be floating-point numbers, or strings, or both. H ow the value of a variableis interpreted depends 
upon its context. If used in anumevic expression, it will be treated asa numbe;; if used asa string, it will be treated asa 
csring. 


To force a variable to be treated asa numbe,, add 0 to it; to force it to be treated as a string, concatenate it with the null 
string. 


W hen astring must be converted to anumbe,, the conversion is accomplished using atof(3). A number isconverted to a 
string by using the value of convemt as a format string for sprintt(3), with the numeric value of the variable as the argument. 
H owever, even though all numbers in awk are floating-point, integral values are always converted as integers. Thus, given this: 
CONVFMT = "%2.2f" 

a =12 

b =a" 


the variable b has a string value of 12 and not 12.00. 


gawk performs comparisons as follows: If two variables are numeric, they are compared numaiically. If one value is numeric 
and the other has a string value that is a “numaric string,” then comparisons are also done numerically. O therwise, the 
numeric value is converted to a string and a string comparison is performed. T wo strings are compared, of course, as strings. 
According to the standard, even if two strings are numeric strings, anumeric comparison is performed. H owever, this is 
clearly incorrect, and gawk doesnot do this. 


U ninitialized variables have the numeric value @ and the string value "" (the null, or empty, string). 


PATTERNS AND ACTIONS 


awk is aline-oriented language. The pattern comes first, and then the action. Action statements are enclosed in and .BR. 
Either the pattern may be missing, or the action may be missing, but, of course, not both. If the pattern is missing, the action 
will be executed for every single line of input. A missing action is equivalent to 


{ print } 
which prints the entire line 


Comments begin with the# character, and continue until the end of the line. Blank lines may be used to separate state- 
ments. N ormally, a statement ends with anewline however, this is not the case for lines ndingina,, {, ?, :, & or !!. Lines 
ending in do or else also have thar statements automatically continued on the following line In other cases, a line can be 
continued by ending it with a\, in which case the newline will be ignored. 


M ultiple statements may be put on one line by separating them with a semicolon. This applies to both the statenents within 
the action part of a pattern-action pair (the usual case), and to the pattern-action statements thensd ves. 


PATTERNS 
awk patterns may be one of the following: 


BEGIN 

END 

/regular expression/ 
relational expression 
pattern && pattern 

pattern jj pattern 

pattern ? pattern : pattern 
(pattern) 
! pattern 
patternl, pattern2 


BEGIN and END are two Special kinds of patterns that are not tested against the input. T he action parts of all Bean patterns are 
merged as if all the statements had been written in a single Bein block. T hey are executed before any of theinput is read. 
Similarly, all the enn blocks are merged, and executed when all the input is exhausted (or when an exit statement is 
executed). BEGIN and END patterns cannot be combined with other patterns in pattern expressions. BEGIN and END patterns 
cannot have missing action parts. 





For /regular expression/ patterns, the associated statement is executed for each input line that matches the regular 
expression. Regular expressions are the same as those in egrep(1), and are summarized as follows: 
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Arelational expression may use any of the operators defined later in the section on actions. T hese generally test whether 
cettain fields match certain regular expressions. 


The aa, |!, and ! operators are logical ano, logical or, and logical not, respectively, asin C. They do short-circuit evaluation, 
also asin C, and are used for combining more primitive pattern expressions. Asin most languages, parentheses may be used 
to change the order of evaluation. 


The ?: operator islike the same operator in C. If the first pattern is true, then the pattern used for testing is the second 
pattern; otherwise, it is the third. O nly one of the second and third patterns is evaluated. 


Thepatterni, pattern2 form of an expression is called arangepattern. It matches all input records starting with a line that 
matches patterni, and continuing until arecord that matchespatt ern2, inclusive It does not combine with any other sort of 
pattern expression. 


REGULAR EXPRESSIONS 
Regular expressions are the extended kind found in egrep. T hey are composed of characters as follows: 
c M atches the non-meta-character c. 
\c M atches the literal character c. 


M atches any character except newline 
M atches the beginning of aline or a string. 


$ M atches the end of aline or astring. 

[abc... ] Character class, matches any of the characters abc.... 

[°abc... J N egated character class, matches any character except abc... and newline 
rlir2 Alternation: matches either r1 orr2. 

rir2 Concatenation: matchesr1, and then r2. 

r+ M atches oneor morers. 

r* M atches zero or morers. 

1? M atches zero or oners. 


(r) Grouping: matches r. 
T he escape sequences that are valid in string constants are also legal in regular expressions. 


ACTIONS 
Action statements are enclosed in braces, ¢ and }. Action statements consist of the usual assignment, conditional, and looping 
statements found in most languages. T he operators, control statements, and input/output statements available are patterned 
after thosein C. 

OPERATORS 
The operators in awk, in order of increasing precedence, are 


=t=- 


Assignment. Both absolute assignment (var = value) and operator-assignment (the other forms) are 


t= [= %= 7= supported. 

2: TheC conditional expression. Thishas the form expr1 ? expr2 : expr3 .lfexpri is true, the value of the 
expression iSexpr2; otherwise it iSexpr3. Only one of expr2 and expr3 is evaluated. 

He Logical or. 

&& Logical ano. 

“yr Regular expression match, negated match. NOTE: Do not usea constant regular expression (/foo/) to the 
left of a~ or !~. Only useoneon the right side. The expression /foo/ ~ exp hasthesame meaning as ( ($0 
~ /f00/) ~ exp). Thisis usually not what was intended. 

<>, <== The regular relational operators. 

blank String concatenation. 


+ Addition and subtraction. 
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M ultiplication, division, and modulus. 

Unary plus, unary minus, and logical negation. 

Exponentiation (** may also be used, and «*= for the assignment operator). 
Increment and decrement, both prefix and postfix. 

Field reference 


CONTROL STATEMENTS 
Thecontrol statements are as follows: 


if (condition) statement [ else statement ] 
while (condition) statement 

do statement while (condition) 

for (expri1; expr2; expr3) statement 

for (var in array) statementbreak 


cont 


inue 


delete array[index] 
delete array 

exit [ expression ] 
{ statements } 


1/0 STATEMENTS 
Theinput/output statements are as follows: 





close (filename) Closefile (or pipe, see paragraph following this list). 

getline Sé $e from next input record; set NF, NR, FNR. 

getline <file Se $0 from next record of fi |e; set NF. 

getline var Set var from next input record; set NF, FNR. 

getline var <file Se var from next record of file. 

next Stop processing the current input record. T he next input record is read and processing starts 
over with the first pattern in the awk program. If the end of the input data is reached, the 
END block(s), if any, are executed. 

next file Stop processing the current input file. The next input record read comes from the next 
input file. FILENAME is updated, FNR is reset to 1, and processing starts over with the first 
pattern in the awk program. If the end of the input data is reached, the enp block(s), if any, 
are executed. 

prin Prints the current record. 

print expr-list Prints expressions. Each expression is separated by the value of the ors variable T he output 
record is terminated with the value of the ors variable. 

print expr-list >file Prints expressions on file. Each expression is separated by the value of the ors variable The 
output record is terminated with the value of the ors variable 

printf fmt, expr-list Format and print. 

printf fmt, expr-list >file Formatandprintonfile. 

system(cmd- line) Execute the command cmd-!ine, and return the exit status. (This may not be available on - 


POSIX systems.) 


O ther input/output redirections are also allowed. For print and printf, >>file appends output to thefile, while | command 
writes on apipe In asimilar fashion, command | getline pipesinto getline. T he getline command will return @ on end of 
file, and -1 on an error. 


THE printf STATEMENT 


The awk versions of the printf statenent and sprintt() function accept the following conversion specification formats: 


%¢ 


An ASCII character. If the argument used for %c isnumeric, it is treated as a character and printed. 
Otherwise, the argument is assumed to be astring, and the only first character of that string is printed. 
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A decimal number (the integer part). 

Just like sa. 

A floating-point number of the form [-]d.ddddddE[ +-]dd. 

A floating-point number of the form [-Jddd.dddddd. 

Usee or ¢ conversion, whichever is shorter, with nonsignificant zeros suppressed. 
An unsigned octal number (again, an integer). 

A character string. 

An unsigned hexadecimal number (an integer). 

Like sx, but using ABCD EF instead of abcdef. 

A single * character; no argument is converted. 


vg ce P © C2 LP Ce eh & 
<x <X¥ DH OD @ > OD BP & 


xe 
3e 


There are optional, additional parameters that may lie between the x and the control letter: 
- The expression should be left-justified within its field. 


width The field should be padded to this width. If the number has a leading zero, then the field will be padded 
with zeros. O therwise, it is padded with blanks. This applies even to the nonnumeric output formats. 
prec A number indicating the maximum width of strings or digits to the right of the decimal point. 


The dynamic width and prec capabilities of the C printt() routines are supported. A * in place of either the width or prec 
specifications will cause ther values to be taken from the argument list to printf or sprintf(). 


SPECIAL FILEN AMES 


When doing!/O redirection from either print or printf into afile, or via getline from a file, gawk recognizes certain special 
filenames internally. T hese filevames allow access to open file descriptors inherited from gawk’s parent process (usually the 
shell). O ther special filenames provide access information about the running gawk process. The filenames are 


/dev/pid Reading thisfilereturns the process|D of the current process, in decimal, terminated with a newline. 

/dev/ppid Reading thisfile returns the parent process 1D of the current process, in decimal, terminated with a 
newline 

/dev/pgrpid Reading thisfile returns the process group ID of the current process, in decimal, teminated with a 
newline 

/dev/user Reading thisfilereturns a single record terminated with a newline The fields are seoarated with blanks. $1 


is the value of the getuia(2) system call, $2 isthe value of the geteuid(2) system call, $3 is the value of the 
getgid(2) system call, and $4 is the value of the getegia( 2) system call. If there are any additional fidds, 
they are the group ID s returned by getgroups(2). M ultiple groups may not be supported on all systems. 


/dev/stdin The standard input. 

/dev/stdout The standard output. 

/dev/stderr The standard error output. 

/dev/fd/n The file associated with the open file descriptor n. 


T hese are particularly useful for error messages. For example, you could use 
print "You blew it!" > "/dev/stderr" 

whereas you would otherwise have to use 

print "You blew it!" j "cat 1>82" 


T hese filenames may also be used on the command lineto name data files. 


NUMERIC FUNCTIONS 
awk has the following predefined arithmetic functions: 


atan2(y, x) Returns the arctangent of y/x in radians. 
cos(expr ) Returns the cosine in radians. 





exp(expr ) The exponential function. 

int (expr) T runcates to integer. 

log(expr ) The natural logarithm function. 

rand() Returns a random number between 0 and 1. 

sin(expr ) Returns the sinein radians, 

sqrt(expr ) The square root function. 

srand (expr ) Useexpr as anew seed for the random number generator. If no expr is provided, the time of day will be 

used. The return value is the previous seed for the random number generator. 
STRING FUNCTIONS 

awk has the following predefined string functions: 

gsub(r, s, t) For each substring matching the regular expression in the stringt , substitute the strings, 
and return the number of substitutions. If t isnot supplied, use $a. 

index(s, t ) Returns theindex of the stringt in thestrings,or aif t isnot present. 

length(s ) Returns the length of thestrings, or the length of sa ifs isnot supplied. 

match(s, 1) Returns the position in s where the regular expression r occurs, or aif u isnot present, and 
sets the values of RSTART and RLENGTH. 

split(s, a, 1) Splitsthe strings into the array a on theregular expression , and returns the number of 
fidds. If r is omitted, Fs is used instead. T he array a is cleared first. 

sprintf (fmt, expr-list) Printsexpr-list according tof mt, and returns the resulting string. 

sub(r, s, t) Just like gsub(), but only the first matching substring is replaced. 

substr(s, i, n) Returns then-character substring of s starting ati . If n isomitted, the rest of s is used. 

tolower (str ) Returns a copy of thestringstr, with all the uppercase charactersin str translated to their 
corresponding lowercase counterparts. N onalphabetic characters are left unchanged. 

toupper (str ) Returns a copy of the string str, with all the lowercase characters in str translated to ther 


corresponding uppercase counterparts. N onalphabetic characters are left unchanged. 


TIME FUNCTIONS 


Since one of the primary uses of awk programs is processing log files that contain time stamp information, gawk provides the 
following two functions for obtaining time stamps and formatting them. 


systime() Returns the current time of day as thenumber of seconds sincethe Epoch (Midnight UTC, 
January 1, 1970 on systems). 

strftime(format, timestamp) | Formatstimestamp according to the specification informat. Thetimestamp should be of the 
same form as returned by systime().Iftimest amp is missing, the current time of day is used. 
See the specification for the strftime() function in C for the format conversions that are 
guaranteed to be available A public-domain version of strftime(3) and aman page for it are 
shipped with gawk; if that version was used to build gawk, then all of the conversions 
described in that man page are availableto gawk. 


STRING CONSTANTS 


String constants in awk are sequences of characters enclosed between double quotes ("). Within strings, certain escape 
sequences are recognized, asin C. These are 


\\ A literal backslash. 

\a The “alert” character; usually the ASCII BEL character. 
\b Backspace. 

\f Formfeed. 


\n N ewline. 
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\r Carriage return. 
\t H orizontal tab. 
\v Vertical tab. 


\xhex digits The character represented by the string of hexadecimal digits following the\x. Asin C, all following 
hexadecimal digits are considered part of the escape sequence. (T his feature should tal us something about 
language design by committee.) For example, "\x1B" isthe ASCII ESC (escape) character. 


\ddd The character represented by the 1-, 2-, or 3-digit sequence of octal digits. For example, "\a33" isthe 
ASCII ESC (escape) character. 
\c The literal character c. 


The escape sequences may also be used inside constant regular expressions (for example, /[\\t\f\n\r\v]/ matches whitespace 
characters). 


FUNCTIONS 


Functions in awk are defined as follows: 


function name (parameter list) { statements } 


Functions are executed when called from within the action parts of regular pattern-action statements. Actual parameters 
supplied in the function call are used to instantiate the formal parameters declared in the function. Arrays are passed by 
reference, other variables are passed by value. 


Functions were not originally part of the awk language, so the provision for local variables is rather clumsy: T hey are declared 
as extra parameters in the parameter list. The convention is to separate local variables from real parameters by extra spaces in 
the parameter list. For example 


function f(p, q, a, b) { #a & b are local 
Jabc/ { ... 5 f(1, 2) 5... } 


The left parenthesisin a function call isrequired to immediately follow the function name, without any intervening 
whitespace. T hisis to avoid a syntactic ambiguity with the concatenation operator. T his restriction does not apply to the 
built-in functions listed earlier. 


Functions may call each other and may be recursive. Function parameters used as local variables are initialized to the null 
string and the number zero upon function invocation. 


The word func may be used in place of function. 


EXAMPLES 


Print and sort the login names of all users: 
BEGIN { FS = ":" } 

print $1 j "sort" } 

Count lines in afile 


nlines++ } 
END { print nlines } 


Precede each line by its number in the file: 
print FNR, $0 } 


Concatenate and line number (a variation on a theme): 
print NR, $0 } 
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SEE ALSO 


egrep(1), getpid(2), getppid(2), getpgrp(2), getuid(2), geteuid(2), getgid(2), getegid(2), get -groups(2) 


TheAWK Programming Language Alfred V. Aho, Brian W. Kernighan, Peter |. Weinberger, Addison-W esley, 1988. ISBN 
0-201-07981-X. 


TheGAWK M anual, Edition 0.15, published by the Free Software Foundation, 1993. 
POSIX COMPATIBILITY 


A primary goal for gawk is compatibility with the standard, as well as with the latest version of awk. To this end, gawk 
incorporates the following user-visible features that are not described in the awk book, but are part of awk in System V 
Release 4, and are in the standard. 





The -v option for assigning variables before program execution starts is new. The book indicates that command-line variable 
assignment happens when awk would otherwise open the argument as a file, which is after the Beatin block is executed. 

H owever, in earlier implenentations, when such an assignment appeared before any filenames, the assignment would happen 
before the Bean block was run. Applications came to depend on this “feature.” When awk was changed to match its 
documentation, this option was added to accommodate applications that deoended upon the old behavior. (This feature was 
agreed on by both the AT&T and GNU devdopers.) 

The -w option for implenentation-specific features is from the standard. 

W hen processing arguments, gawk uses the special option -- to signal the end of arguments. In compatibility mode, it will 
warn about, but otherwise ignore, undefined options. In normal operation, such arguments are passed on to the awk program 
for it to process. 

The awk book does not define the return value of srand(). The System V Release 4 version of awk (and the standard) has it 
return the seed it was using, to allow keeping track of random number sequences. Therefore, srand() in gawk also returns its 
current seed. 

O ther new features are: the use of multiple -F options (from M KS awk); the environ array; the \a, and \v escape sequences 
(done originally in gawk and fed back into AT & T's version); the tolower() and toupper() built-in functions (from AT & T); 
and theC conversion specifications in printf (done first in AT & T's version). 


GNU EXTENSIONS 


gawk has some extensions to awk. T hey are described in this section. All the extensions described here can be disabled by 
invoking gawk with the -w compat option. 


The following features of gawk are not available in awk: 

The \x escape sequence. 

The systime() and strftime() functions. 

The special filenames available for 1/O redirection are not recognized. 

The arGino and errno variables are not special. 

The 1Gnorecase variable and its side effects. 

The FIELDwIDTHs variable and fixed width field splitting. 

No path search is performed for files named via the -¢ option. T herefore, the awkPatH environment variable is not special. 
Theuse of next file to abandon processing of the current input file 

Theuse of delete array to delete the entire contents of an array. 

The awk book does not define the return value of the close() function. gawk’S close() returns the value from fclose(3), or 
pclose(3), when closing afile or pipe, respectively. 


W hen gawk isinvoked with the -w compat option, if the fs argument to the -F option ist, then Fs will be set to the tab 
character. Since thisis a rather ugly special case, it is not the default behavior. T his behavior also does not occur if -wposix 
has been specified. 
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HISTORICAL FEATURES 


T hee are two features of historical awk implementations that gawk supports. First, it is possible to call the length() built-in 
function not only with no argument, but even without parentheses! T hus, this: 


a = length 

is the same as ether of these: 
a = length() 

a = length($0) 


This feature is marked as “deprecated” in the standard, and gawk will issue a warning about its use if -w 1int is specified on 
the command line 


The other feature is the use of either the continue or the break statements outside the body of awhile, for, or do loop. 
Traditional awk implementations have treated such usage as equivalent to the next statement. gawk will support this usage 
if -w compat has been specified. 


ENVIRONMENT VARIABLES 


If POSIXLY_CORRECT exists in the environment, then gawk behaves exactly as if — -posix had been specified on the command 
line If —-1int has been specified, gawk will issue a warning message to this effect. 


BUGS 
The -F option is not necessary given the command-line variable assignment feature; it remains only for backwards compat- 
ibility. 
If your system actually has support for /dev/fa and the associated /dev/stdin, /dev/stdout, and /dev/stderr files, you may get 
different output from gawk than you would get on asystem without those files. When gawk interprets these files internally, it 
synchronizes output to the standard output with output to /dev/stdout, while on a system with those files, the output is 
actually to different open files. C aveat emptor. 


VERSION INFORMATION 
This man page documents gawk, version 2.15. 


Starting with the 2.15 version of gawk, the -c, -v, -c, -D, -a, and -e options of the 2.11 version areno longer recognized. T his 
fact will not even be documented in the manual page for the next major version. 


AUTHORS 
The original version of awk was designed and implenented by Alfred Aho, Peter Weinberger, and Brian Kernighan of AT&T 
Bdl Labs. Brian Kernighan continues to maintain and enhanceit. 


Paul Rubin and J ay Fenlason, of the Free Software Foundation, wrote gawk, to be compatible with the original version of awk 
distributed in the seventh edition. John W oods contributed anumber of bug fixes. D avid Trueman, with contributions from 
Arnold Robbins, made gawk compatible with the new version of awk. Arnold Robbins is the current maintaine. 


Theinitial DOS port was done by Conrad K wok and Scott Garfinkle Scott D efik is the current DOS maintainer. Pat 
Rankin did the port to VMS, and M ichal J aegermann did the port to the Atari ST. The port to O S/2 was done by Kai Uwe 
Romme, with contributions and hap from D arrel H ankerson. 


BUG REPORTS 
If you find a bug in gawk, please send electronic mail to 


bug-gnu-utils@prep.ai.mit.edu, 


with a copy to arnold@gnu.ai.mit.edu. Please include your operating system and its revision, the version of gawk, what C 
compiler you used to compile it, and a test program and data that are as small as possible for reproducing the problen. 
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Before sending a bug report, please do two things. First, verify that you have the latest version of gawk. M any bugs (usually 
subtle ones) are fixed at each rdease, and if yours is out of date, the problen may already have been solved. Second, please 
read this man page and the reference manual carefully to be sure that what you think is a bug really is, instead of just a quirk 
in the language. 

ACKNOWLEDGMENTS 
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W ethank him. 
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gcal 
gcal— Displays month/year calendar sheets, eternal holiday lists for Julian and Gregorian years, and fixed date warning 
lists— all in a variety of ways. 


SYNOPSIS 


gcal [[ Option... ][%Date ][@File... ]] [ Command 


DESCRIPTION 
gcal isa program similar the standard calendar programs Bsp-'cal' and calendar. 
geal displays Gregorian calendars, J ulian calendars (before Seotember 1752). 
If gcai is started without any options or commands, a calendar of the current month is displayed. 


If the calendar of a definite year is wanted, the year must be fully specified. For example, gcal 94 displays a year calendar of 
the year 94, not of the year 1994. 


If two arguments are given in thecommand part, the first argument denotes the month and the second argument denotes the 
year. In case any illegal commands are given running geal, the program will use internal defaults. 


The Gregorian R formation is assumed to have occurred in 1752 on the 3rd of September. T en days following that date 
were eliminated by the reformation, so the calendar for that month is a bit unusual. 


MORE PROGRAM INFORMATION 
You get more program information if you start gcai as follows: 
gcal -h gcal -? gcal -help 
resp., 
gcal -hh gcal -?? gcal -long-help[=ARG]j[=?] gcal -usage[=ARG]j[=?] 
A hypertext file gcal.info containing detailed online information should be available which you can inspect using your 
GNU Infobrowser. 


COPYRIGHT 


geal copyright © 1994, 1995, 1996 by Thomas Esken. T his software doesn’t claim completeness, correctness, or usability. 
On principle | will not be liable for any damages or losses (implicit or explicit), which result from using or handling my 
software. If you use this software, you agree without any exception to this agreement, which binds you legally. 

geal is free software and distributed under the terms of the GNU General Public License; published by the Free Software 
Foundation; version 2 or (at your option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposals for contract work, and so forth are welcome! 
If you like this tool, |’d appreciate a postcard from you! 

Enjoy it =8") 


174 Part |: User Commands 


AUTHOR 
Thomas Esken (esken@uni-muenster.de) 
Im H agenfeld 84 
D-48147 M uenste; Germany 
Phone: +49 251 232585 


SEE ALSO 


cal(1), calendar(1) 


16 July 1996 
QCC, grt 
gec, gt+t GNU project C and CH Compiler (v2.7) 
SYNOPSIS 
gcc [ option j filename ]... 
gt+ [ option j filename ]... 
WARNING 


Theinformation in this man pageisan extract from the full documentation of the GNU C compiler and is limited to the 
meaning of the options. 


This man page is not keot up-to-date exceot when volunteers want to maintain it. If you find a discrepancy between the man 
page and the software, please check the info file, which is the authoritative documentation. 


If we find that the things in this man page that are out of date cause significant confusion or complaints, we will stop 
distributing the man page. The alternative, updating the man page when we update the info file, is impossible because the 
rest of the work of maintaining GNU CC leavesus no timefor that. The GNU project regards man pages as obsolete and 
should not le them take time away from other things. 


For complete and current documentation, refer to the info file gcc or the manual U sng and Porting GNU CC (for version 
2.0). Both are made from the T exinfo source file gcc. texinfo. 
DESCRIPTION 


TheC and C ++compilers are integrated. Both process input files through one or more of four stages: preprocessing, 
compilation, assembly, and linking. Source filerame suffixes identify the source language, but which name you use for the 
compiler governs default assumptions: 

gcc Assumes preprocessed (.i) filesareC and assumes C-style linking. 

gt+ Assumes preprocessed (.i) files are C +- and assumes C ++style linking. 


Suffixes of source filenames indicate the language and kind of processing to be done: 


.c C source; preprocess, compile, assanble 

.C C ++source preprocess, compile, assemble 

.cC C ++source preprocess, compile, assemble 

.CXX C ++source preprocess, compile, assemble 

m Objective-C source; preprocess, compile assemble 
Bi Preprocessed C; compile, assemble 

vii Preprocessed C -++ compile, assemble 


1S Assembler source; assemble 


gee gt+ 175 


8 Assembler source; preprocess, assemble 
A Preprocessor file; not usually named on command line 
Files with other suffixes are passed to the linker. Common cases include 


-0 Object file 
.a Archive file 


Linking is always the last stage unless you use one of the -c, -s, or -E options to avoid it (or unless compilation errors stop 
the whole process). For the link stage, all .o files corresponding to sourcefiles, -1 libraries, unrecognized filenames (including 
named .o object files, and .a archives) are passed to the linker in command-line order. 

OPTIONS 
O ptions must be separate -dr is quite different from -a -r. 


M ost - and -w options have two contrary forms: -fname and -fno-name (OF -Wname and -Wno-name). Only the nondefault forms 
are shown here 


H ereisasummary of all the options, grouped by type. Explanations arein the following sections. 
Overall 0 ptions 


-c -S -E -o file -pipe -v -x | anguage 





Language O ptions 
-ansi -fall-virtual -fcond-mismatch 
-fdollars-in-identifiers -fenum-int-equiv -fexternal-templates 
-fno-asm -fno-builtin -fno-strict-prototype 
-fsigned-bitfields -fsigned-char -fthis-is-variable 
-funsigned-bitfields -funsigned-char -fwritable-strings 
-traditional -traditional-cpp -trigraphs 

Warning Options 
-fsyntax-only -pedantic -pedantic-errors 
-w -W -Wall -Waggregate-return -Wcast-align 
-Wcast-qual -Wchar-subscript —-Wcomment 
-Wconversion -Wenum-clash -Werror 
-Wformat -Wid-clash-len -Wimplicit 
-Winline -Wmissing-prototypes -Wmissing-declarations 
-Wnested-externs -Wno-import -Wparentheses 
-Wpointer-arith -Wredundant-decls -Wreturn-type 
-Wshadow -Wstrict-prototypes -Wswitch 
-Wtemplate-debugging -Wtraditional -Wtrigraphs 
-Wuninitialized -Wunused -Wwrite-strings 

Debugging O ptions 


-a -dietters -fpretend-float -g -glevel -gcoff -gxcoff -gxcoff+ -gdwarf -gdwarf+ -gstabs -gstabs+ -ggdb -p -pg - 
save- temps -print-file-name=library -print-libgcc-file-name - print-prog-name=program 


Optimization O ptions 


-fcaller-saves -fcse-follow-jumps -fcse-skip-blocks 
-fdelayed-branch -felide-constructors -fexpensive-optimizations 
-ffast-math -ffloat-store -fforce-addr 


-fforce-mem -finline-functions -fkeep-inline-functions 
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-fmemorize-lookups -fno-default-inline -fno-defer-pop 
-fno-function-cse -fno-inline -fno-peephole 
-fomit-frame-pointer -frerun-cse-after-loop -fschedule-insns 
-fschedule-insns2 -fstrength-reduce -fthread-jumps 
-funroll-all-loops -funroll-loops -0 -02 


Preprocessor O ptions 


-Aassertion -C -dD -dM -dN -Dmacro[=defn ]-E -H- idirafter dir -include file -imacrosfile -iprefix file - 
iwithprefix dir -M -MD -MM -MMD -nostdinc -P -Umacro -undef 


Assembler O ption 
-Wa,option 
Linker Options 
-lli brary -nostartfiles -nostdlib -static -shared -symbolic -Xlinkernopti on -Wl,option -u symbol 
Directory 0 ptions 
-Bprefix -Idir -I- -Ldi 
Target Options 
-b machine -V version 
Configuration-D ependent O ptions 
M 680x0 O ptions 


-m68000-m68020 -m68020-40-m68030-m68040-m68881 -mbitfield -mc68000 -mc68020 -mfpa -mnobitfield -mrtd -mshort -msoft- 
float 


VAX Options 

-mg -mgnu -munix 
SPARC Options 

-mepilogue -mfpu -mhard-float -mno-fpu -mno-epilogue -msoft-float -msparclite -mv8 -msupersparc -mcypress 
Convex 0 ptions 

-margcount -mc1 -mc2 -mnoargcount 


AMD 29K Options 


-M29000-m29050 -mbw -mdw -mkernel-registers -mlarge -mnbw -mnodw -msmall -mstack-check -muser-registers 


M 88K Options 
-m88000 -m88100 -m88110 -mbig-pic 
-mcheck-zero-division -mhandle-large-shift 
-midentify-revision -mno-check-zero-division 
-mno-ocs-debug-info -mno-ocs-frame-position 
-mno-optimize-arg-area -mno-serialize-volatile 
-mno-underscores -mocs-debug-info 
-mocs-frame-position -moptimize-arg-area 
-mserialize-volatile -mshort-data-num 
-msvr3 -msvr4 -mtrap-large-shift 
-muse-div-instruction -mversion-03.00 


-mwarn-passed-structs 


RS6000 Options 
-mfp-in-toc -mno-fop-in-toc 

RT Options 
-mcall-lib-mul 
-mfull-fp-blocks 


-mfp-arg-in-fpregs 

-mhc-struct-return 

-mminimum-fp-blocks 
MIPS Options 

-Mcpu=cpu type -mips2 -mips3 

-mlonglong128 

-mno-rnames 

-mno-stats -mmemcpy -mno-memcpy -mno-mips-tfile 

-mmips-tfile 

-mno-abicalls -mhalf-pic -mno-half-pic -G num -nocpp 
i386 Options 

-m486 -mno-486 - msoft-float - mno-fp-ret-in-387 
HPPA Options 


gcc, g++ 


-mfp-arg-in-gregs 
-min-line-mul 


-mnohce-struct-return 


-mint64 -mlong64 


-mmips-as -mgas -mrnames 
-mgpopt -mno-gpopt -mstats 
-msoft-float -mhard-float -mabicalls 


-mpa-risc- 1-0 -mparisc- 1-1 -mkernel -mshared- libs - mno-shared-libs - mlong- calls - mdisable-fpregs - mdisable- 


indexing - mtrailing-colon 
i960 Options 

-mcpu-type 

-mnumerics -msoft-float 
-mno-leaf-procedures -mtail-call 
-mcomplex-addr -mno-complex-addr 
-mno-code-align -mic-compat 
-mic3.Q@-compat -masm-compat 
-mstrict-align -mno-strict-align 


-mno-old-align 


DEC Alpha O ptions 


-mfp-regs -mno-fp-regs -mno-soft-float -msoft-float 


System V O ptions 
-G -Qy -Qn -YP,paths -Ym,dir 

Code-G meation Options 
-fcall-saved-reg -fcall-used- 
reg -ffixed-reg -finhibit- 
size-directive -fnonnull- 
objects -fno-common -fno-ident 
-fno-gnu-linker -fpcc-struct- 
return -fpic -fPIC -freg- 
struct- return -fshared-data - 
fshort-enums -fshort-double - 
fvolatile -fvolatile-global - 


fverbose-asm 


-mleaf-procedures 
-mno-tail-call 
-mcode-align 
-mic2.Q-compat 
-mintel-asm 


-mold-align 
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OVERALL OPTIONS 


-x language 


-xX none 


Specify explicitly the! anguage for the following input files (rather than choosing a default based on the 
filename suffix). This option applies to all following input files until the next -x option. Possible values of 
language are c, objective-c, c-header, c++, cpp-output, assembler, and assembler-with-cpp 

Turn off any specification of a language, so that subsequent files are handled according to their filename 
suffixes (as they are if -x has not been used at all). 


If you want only some of the four stages (preprocess, compile, assemble, link), you can use -x (or filename suffixes) to tell gcc 
where to start, and one of the options -c, -s, or -E to say where gcc isto stop. N ote that some combinations (for example, -x 
cpp-output -E) instruct gcc to do nothing at all. 


-c 





Compile or assemble the source files, but do not link. The compiler output is an object file corresponding 
to each source file 

By default, gec makes the object filename for a source file by replacing the suffix .c, .i, .s, and so on, with 
.o. Use -o to sdect another name 

gec ignores any unrecognized input files (those that do not require compilation or assembly) with the -c 
option. 


-S Stop after the stage of compilation proper; do not assemble. T he output is an assembler code file for each 
nonassanbler input file specified. 

By default, gec makes the assembler filename for a source file by replacing the suffix .c, .i, and so on, with 
.s. Use -o to sdect another name 
gcc ignores any input files that don’t require compilation. 

-E Stop after the preprocessing stage; do not run the compiler proper. The output is preprocessed source 
code, which is sent to the standard output. 
gcc ignores input files that don’t require preprocessing. 

-o file Place output in filefile. This applies regardless to whatever sort of output gcc is producing, whether it be 
an executable file, an object file, an assembler file, or preprocessed C code. 

Since only one output file can be specified, it does not make sense to use -o when compiling more than 
oneinput file unless you are producing an executable file as output. 

If you do not specify -o, the default is to put an executable file in a.out, the object filefor source .suffix in 
source.o, its assembler filein source.s, and all preprocessed C source on standard output. 

-v Print (on standard error output) the commands executed to run the stages of compilation. Also print the 
version number of the compiler driver program and of the preprocessor and the compiler proper. 

-pipe Use pipes rather than tenporary files for communication between the various stages of compilation. This 
fails to work on some systems where the assembler cannot read from apipe; but the GN U assembler has 
no trouble. 

LANGUAGE OPTIONS 


The following options control the dialect of C that the compiler accepts: 


-ansi 


Support all AN SI standard C programs. 


This turns off certain features of GN U C that are incompatible with AN SI C, such as the asm, 
inline, and typeof keywords, and predefined macros such as unix and vax that identify the type 
of system you are using. It also enables the undesirable and rardy used AN SI trigraph feature, 
and disallows$ as part of identifiers. The alternate keywords _asm_, _extension_, 
__inline_, and __typeof__ continue to work despite -ansi. You would not want to use then 
in an ANSI C program, of course, but it is useful to put then in header files that might be 
included in compilations done with -ansi. Alternate predefined macros such as__unix__ and 
__vax__ are also available, with or without -ansi. 

The -ansi option does not cause non-AN SI programs to be rected gratuitously. For that, - 
pedantic iS required in addition to -ansi. 


-fno-asm 


-fno-builtin 


-fno-strict-prototype 


-trigraphs 


-traditional 


raditional-cpp 


dollars-in-identifiers 


enum-int-equiv 





external-templates 


-fall-virtual 


-fcond-mismatch 


-fthis-is-variable 


-funsigned-char 
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The preprocessor predefines amacro __sTRICT_ANSI__ when you use the -ansi option. Some 
header files may notice this macro and refrain from declaring certain functions or defining 
certain macros that the AN SI standard doesn’t call for; this is to avoid interfering with any 
programs that might use these names for other things. 

Do not recognize asm, inline, Of typeof aSa keyword. T hese words may then be used as 
identifiers. You can use__asm_, __inline_, and __typeof__ instead. -ansi implies -fno-asm. 
Don’t recognize built-in functions that do not begin with two leading underscores. Currently, 
the functions affected include exit, abort, abs, alloca, cos, exit, fabs, labs, memcmp, memcpy, 
sin, sqrt, strcmp, strepy,and strlen. 

The -ansi option prevents alloca and _ exit from being built-in functions. 

Treat a function declaration with no arguments, such as int foo();, aSC would treat it— as 
saying nothing about the number of arguments or their types (C ++ only). N ormdlly, such a 
declaration in C ++ means that the function foo takes no arguments. 

Support AN SI C trigraphs. The -ansi option implies -trigraphs. 

Attempt to support some aspects of traditional C compilers. For details, see theGNU C 

M anual; the duplicate list here has been deleted so that we won’t get complaints when it is out 
of date. 

But one note about C ++ programs only (not C). -traditional has one additional effect for 
C+ assignment to this is permitted. This is the same as the effect of -fthis-is-variable. 


Attempt to support some aspects of traditional C preprocessors. T his includes the items that 
specifically mention the preprocessor previously, but none of the other effects of -traditional. 
Permit the use of $ in identifiers (C ++ only). You can also use -fno-dollars-in-identifiers to 
explicitly prohibit use of $. (GNU C++allows $ by default on some target systems but not 
others.) 

Permit implicit conversion of int to enumeration types (C ++only). Normally GNU C++ 
allows conversion of enum to int, but not the other way around. 


Produce smaller code for tenplate declarations, by generating only asingle copy of each 
template function where it is defined (C ++ only). To use this option successfully, you must also 
mark all files that use templates with ether #pragma implementation (the definition) or #pragma 
interface (declarations). 
When your code is compiled with -fexternal-templates, all tanplate instantiations are external. 
You must arrange for all necessary instantiations to appear in the implementation file you can 
do this with a typedet that references each instantiation needed. Conversely, when you compile 
using the default option -fno-external-templates, all tanplate instantiations are explicitly 
internal. 
T reat all possible menber functions as virtual, implicitly. All member functions (except for 
constructor functions and new or delete member operators) are treated as virtual functions of 
the class where they appear. T his does not mean that all calls to these member functions will be 
made through the internal table of virtual functions. U nder some circumstances, the compiler 
can determine that a call to a given virtual function can be made directly; in these cases, the 
calls are direct in any case. 

Allow conditional expressions with mismatched types in the second and third arguments. The 
value of such an expression is void. 

Permit assignment to this (C ++only). The incorporation of user-defined free store manage 
ment into C++ has made assignment to this an anachronism. Therefore, by default it is invalid 
to assign to this within a class member function. H owever, for backwards compatibility, you 
can make it valid with -fthis-is-variable. 

Let the type char be unsigned, like unsigned char. 

Each kind of machine has a default for what char should be It is ather like unsigned char by 
default or like signed char by default. 
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signed-char 


signed-bitfields 
unsigned-bitfields 


no-signed-bitfields 


-fno-unsigned-bitfields 





writable-strings 


PREPRO CESSOR OPTIONS 


Ideally, a portable program should always use signed char OF unsigned char when it depends on 
the signedness of an object. But many programs have been written to use plain char and expect 
it to be signed, or expect it to be unsigned, depending on the machines they were written for. 
This option, and its inverse, lets you make such a program work with the opposite default. 
The type char is always a distinct type from each of signed char and unsigned char, even though 
its behavior is always just like one of those two. 

Let the type char be signed, like signed char. 

N ote that this is equivalent to -fno-unsigned-char, which is the negative form of -funsigned- 
char. Likewise, -fno-signed-char iS equivalent to -funsigned-char. 

T hese options control whether a bitfidd is sgned or unsigned, when declared with no explicit 
Or unsigned qualifier. 

By default, such a bitfield is signed, because this is consistent: The basic integer types such as 
int 

signed are signed types. 

H owever, when you specify -traditional, bitfields are all unsigned no matter what. 

Store string constants in the writable data segment and don’t uniquize them. T hisis for 
compatibility with old programs which assume they can write into string constants. -tradi- 
tional also has this effect. 

W riting into string constants is a very bad idea; constants should be constant. 


T hese options control the C preprocessor, which isrun on each C source file before actual compilation. 


If you use the -E option, gcc does nothing except preprocessing. Some of these options make sense only together with -c 
because they cause the preprocessor output to be unsuitable for actual compilation. 


-include file 


-imacros file 


-idirafter dir 


-iprefix prefix 


-iwithprefix dir 


-nostdinc 


-nostdinct+ 


-undef 
-E 


-C 


Processtile asinput before processing the regular input file In effect, the contents of file 

are compiled first. Any -p and -u options on the command line are always processed before 
-include file, regardless of the order in which they are written. All the -include and -imacros 
options are processed in the order in which they are written. 

Processtile aSinput, discarding the resulting output, before processing the regular input file 
Because the output generated from file is discarded, the only effect of -imacros file isto make 
the macros defined in file available for use in the main input. The preprocessor evaluates any 
-D and -u options on the command line before processing -imacros file, regardless of the order 
in which they are written. All the -include and -imacros options are processed in the order in 
which they are written. 


Add the directory dir to the second include path. The directories on the second include path 
are searched when a header fileis not found in any of the directoriesin the main include path 
(the one that -1 adds to). 

Specify prefix asthe prefix for subsequent -iwithprefix options. 

Add a directory to the second include path. The directory’s name is made by concatenating 
prefix and dir, whereprefix was specified previously with -iprefix. 

Do not search the standard system directories for header files. O nly the directories you have 
specified with -1 options (and the current directory, if appropriate) are searched. 

By using both -nostdinc and -1-, you can limit the include file search file to only those 
directories you specify explicitly. 

Do not search for header files in the C++ specific standard directories, but do still search the 
other standard directories. (T his option is used when building 1ibg++.) 

Do not predefine any nonstandard macros (including architecture flags). 


Run only theC preprocessor. Preprocess all the C source files specified and output the results to 
standard output or to the specified output file 


Tell the preprocessor not to discard comments. U sed with the -e option. 


cc, g++ 


-P Tall the preprocessor not to generate #1ine commands. U sed with the -c option. 

-M [-MG] Tall the preprocessor to output a rule suitable for make describing the dependencies of each 
object file For each source file, the preprocessor outputs one make -rule whose target is the 
object filename for that source file and whose dependencies are all the files that have ben 
included with #include. T his rule may bea single line or may be continued with \-newline if it 
is long. The list of rulesis printed on standard output instead of the preprocessed C program. 
-m implies -e. 

-m@ says to treat missing header files as generated files and assume they live in the same directory 
as the source file. It must be specified in addition to -m. 


-MM [-MG] Like -m but the output mentions only the user header files included with #include " file ". 
System header files included with #include < file > areomitted. 
-MD Like -u but the dependency information is written to files with names made by replacing .o 


with .d at the end of the output filenames. Thisisin addition to compiling the file as specified; 
-mD does not inhibit ordinary compilation the way - does. 

TheM ach utility ma can be used to merge the .« files into a single dependency file suitable for 
using with the make command. 


MIMD Like -wp except mention only user header files, not system header files. 

-H Print the name of each header file used, in addition to other normal activities. 

-Aquestion (answer ) Assert the answer answer forquestion, in caseit istested with a preprocessor conditional such as 
#if #question (answer ). -A- disables the standard assertions that normally describe the target 
machine. 

-Aquestion ( answer ) Assert the answer answer forquestion, in caseit istested with a preprocessor conditional such as 
#if # question ( answer ). -A-isables the standard assertions that normally describe the target 
machine. 

-Dmacro Define macro macro with the string 1 asits definition. 

-Dmacro=defn Define macro macro aSdefn. All instances of -p on the command line are processed before any 
-U options. 

-Umacr 0 Undefine macro macro. -u options are evaluated after all -p options, but before any -include and 
-imacros options. 

-dM Tell the preprocessor to output only a list of the macro definitions that are in effect at the end 
of preprocessing. U sed with the -e option. 

-dD Tell the preprocessor to pass all macro definitions into the output, in thar proper sequence in 
the rest of the output. 

-dN Like -ap except that the macro arguments and contents are omitted. Only #define name iS 
included in the output. 

ASSEMBLER 0 PTION 

-Wa,option Passoption aSan option to the assembler. If option contains commas, it is split into multiple 

options at the commas. 
LINKER OPTIONS 


T hese options comeinto play when the compiler links object files into an executable output file. T hey are meaningless if the 

compiler is not doing alink step. 

obj ect-file-name A filename that does not end in a special recognized suffix is considered to name an object file 
or library. (O bject files are distinguished from libraries by the linker according to the file 
contents.) If gec does alink step, these object files are used as input to the linker. 

-llibrary Use the library named |i brary when linking. 
The linker searches a standard list of directories for the library, which is actually a file named 
lib library .a. Thelinker then uses thisfileas if it had been specified precisely by name. 
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-lobjc 
-nostartfiles 


-nostdlib 
-static 
-shared 


-symbolic 


-Xlinker option 


-W1, option 


-u symbol 


DIRECTORY OPTIONS 


The directories searched include several standard system directories plus any that you specify 
with -L. 

Normally, the files found this way are library files— archive files whose members are object files. 
The linker handles an archive file by scanning through it for members that define symbols that 
have so far been referenced but not defined. H oweve,, if the linker finds an ordinary object file 
rather than alibrary, the object file is linked in the usual fashion. The only difference between 
using an -1 option and specifying a filename is that -! surrounds! i brary with 1ib and .a and 
searches several directories. 

You need this special case of the -1 option in order to link an O bjectiveC program. 


Do not use the standard systen startup files when linking. T he standard libraries are used 
normally. 

Don’t use the standard system libraries and startup files when linking. O nly the files you specify 
will be passed to the linker. 

On systems that support dynamic linking, this prevents linking with the shared libraries. On 
other systems, this option has no effect. 

Produce a shared object which can then be linked with other objects to form an executable 
Only afew systems support this option. 

Bind references to global symbols when building ashared object. W arn about any unresolved 
references (unless overridden by the link editor option -xlinker -z -Xlinker defs). Only afew 
systems support this option. 

Pass option aS an option to the linker. You can use this to supply system-specific linker options 
which GNU CC does not know how to recognize. 

If you want to pass an option that takes an argument, you must use -Xlinker twice once for the 
option and once for the argument. For example, to pasS-assert definitions, you Must write - 
Xlinker -assert -Xlinker definitions. It does not work to write -xlinker "-assert 
definitions", because this passes the entire string as a single argument, which is not what the 
linker expects. 

Pass option as an option to the linker. If option contains commas, it is split into multiple 
options at the commas. 

Pretend the symbol symbo! is undefined, to force linking of library modules to define it. You 
can use -u multiple times with different symbols to force loading of additional library modules. 


T hese options specify directories to search for header files, for libraries, and for parts of the compiler: 


-Idir 
-I- 


-Ldir 
-Bprefix 


Append directory dir to the list of directories searched for include files. 

Any directories you specify with -1 options before the -1- option are searched only for the case 
Of #include "file"; they are not searched for #include <file>. 

If additional directories are specified with -1 options after the -1-, these directories are searched 
for all #include directives. (Ordinarily all -1 directories are used this way.) 

In addition, the -1- option inhibits the use of the current directory (where the current input file 
came from) as the first search directory for #include " file ". Thereisno way to override this 
effect of -1-. With -1. you can specify searching the directory that was current when the 
compiler was invoked. T hat is not exactly the same as what the preprocessor does by default, 
but it is often satisfactory. 

-1- does not inhibit the use of the standard system directories for header files. Thus, -1- and 
-nostdinc are independent. 

Add directory dir to thelist of directories to be searched for -1. 

This option specifies where to find the executables, libraries, and data files of the compiler itsdf. 
The compiler driver program runs one or more of the subprograms cpp, cc1 (or, for C-H, 
cciplus), as, and 1a. It trieSprefix aSa prefix for each program it tries to run, both with and 
without machine / version /. 
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For each subprogram to be run, the compiler driver first tries the -8 prefix, if any. If that name 
is not found, or if -8 was not specified, the driver tries two standard prefixes, which are /usr/ 
lib/gec/ and /usr/local/1lib/gcc-1ib/. If neither of those results in a filename that is found, the 
compiler driver searches for the unmodified program name, using the directories specified in 
your PATH environment variable. 

Theruntime support file 1ibgcc.a is also searched for using the -B prefix, if needed. If it isnot 
found there, the two standard prefixes (preceding paragraph) are tried, and thatisall. The fileis 
left out of the link if it is not found by those means. M ost of the time, on most machines, 
libgec.a isnot actually necessary. 

You can get a similar result from the environment variable acc_Exec_PREF1X; if it is defined, its 
value is used as a prefix in the same way. If both the -8 option and the acc_Exec_PREFIX variable 
are present, the -B option is used first and the environment variable value second. 


WARNING OPTIONS 


W arnings are diagnostic messages that report constructions that are not inherently erroneous but are risky or suggest there 
may have been an error. 


T hese options control the amount and kinds of warnings produced by GNU CC: 


-fsyntax-only Check the code for syntax errors, but don’t emit any output. 

-w Inhibit all warning messages. 

-Wno- import Inhibit warning messages about the use of #import. 

-pedantic Issue all the warnings demanded by strict AN SI standard C; reject all programs that use 


forbidden extensions. 

Valid AN SI standard C programs should compile properly with or without this option (though 
a rare few will require -ansi). H owever, without this option, certain GNU extensionsand 
traditional C features are supported as well. W ith this option, they are rgected. Thereis no 
reason to use this option; it exists only to satisfy pedants. 

-pedantic does not cause warning messages for use of the alternate keywords whose names begin 
and end with ‘__’. Pedantic warnings are also disabled in the expression that follows extension. 
H owever, only system header files should use these escape routes; application programs should 


avoid then. 
-pedantic-errors Like -pedantic, except that errors are produced rather than warnings. 
-W Print extra warning messages for these events: 


A nonvolatile automatic variable might be changed by a call to 1ongjmp. T hese warnings are 
possible only in optimizing compilation. The compiler sees only the calls to set jmp. It cannot 
know where longjmp will be called; in fact, asignal handler could call it at any point in the code. 
Asaresult, you may get a warning even when theeisin fact no problem because 1ongjmp 
cannot in fact be called at the place which would cause a problan. 

A function can return either with or without a value (Falling off the end of the function body 
is considered returning without a value.) For example, this function would evoke such a 
warning: 

foo (a) 

{ 

if (a > 0) 

return a; 


} 
Spurious warnings can occur because GN U CC does not realize that certain functions 
(including abort and longjmp) will never return. 


An expression-statement or the left side of a comma expression contains no side effects. To 
suppress the warning, cast the unused expression to void. For example, an expression such as 
x[i,j] will causea warning, but x[(void)i,j] will not. 


An unsigned value is compared against zero with > or <=. 
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-Wimplicit 
-Wreturn-type 


-Wunused 


-Wswitch 


-Wcomment 
-Wtrigraphs 
-Wformat 


-Wchar-subscripts 


-Wuninitialized 


W arn whenever a function or parameter is implicitly declared. 


Warn whenever a function isdefined with areturn-type that defaults to int. Also warn about 
any return Statement with no return-value in a function whose return-type iS not void. 


Warn whenever a local variable is unused aside from its declaration, whenever a function is 
declared static but never defined, and whenever a statement computes a result that is explicitly 
not used. 


Warn whenever a switch statement has an index of enumeral type and lacks a case for one or 
more of the named codes of that enumeration. (T he presence of a default label prevents this 
warning.) case labels outside the enumeration range also provoke warnings when this option is 
used. 


W arn whenever a comment-start sequence / appears in acomment. 
W arn if any trigraphs are encountered (assuming they are enabled). 


Check calls to printf and scant, and so on, to make sure that the arguments supplied have 
types appropriate to the format string specified. 


W arn if an array subscript has type char. This is acommon cause of error, as programmers 
often forget that this type is sgned on some machines. 

An automatic variable is used without first being initialized. 

T hese warnings are possible only in optimizing compilation, because they require data flow 
information that is computed only when optimizing. If you don’t specify -o, you simply won’t 
get these warnings. 

T hese warnings occur only for variables that are candidates for register allocation. Therefore, 
they do not occur for a variable that is declared volatile or whose address is taken, or whose size 
is other than 1, 2, 4, or 8 bytes. Also, they do not occur for structures, unions, or arrays, even 
when they are in registers. 

N ote that there may be no warning about a variable that is used only to compute a value that 
itself is never used, because such computations may be deleted by data flow analysis before the 
warnings are printed. 

T hese warnings are made optional because GNU CC isnot smart enough to see all the reasons 
why the code might be correct despite appearing to have an error. H ere is one example of how 
this can happen: 

{ 

int x; 

switch (y) 

{ 

case 1: x = 1; 

break; 

case 2: x = 4; 

break; 

case 3: x = 5; 

} 

foo (x); 

} 


If the value of y is always 1, 2, or 3, then x is always initialized, but GNU CC doesn’t know this. 
H ereis another common case: 
{ 


int save_y; 
if (change_y) save_y =y,y =new_y; 


i wehanias Vy =save_y; 
} 
This has no bug because save_y is used only if it is set. 


Some spurious warnings can be avoided if you declare as volatile all the functions you use that 
never return. 


-Wparentheses 
-Wtemplate-debugging 


-Wall 


W arn if parentheses are omitted in certain contexts. 


W hen using templates in aC ++ program, warn if debugging is not yet fully available (C ++ 
only). 

All of the preceding -w options combined. These are all the options that pertain to usage that 
we recommend avoiding and that we bdieve is easy to avoid, even in conjunction with macros. 


The remaining -w... options are not implied by -wa11 because they warn about constructions that we consider reasonable to 
use, on occasion, in clean programs. 


-Wtraditional 


-Wshadow 
-Wid-clash-| en 


-Wpointer-arith 


-Wcast-qual 


-Weast-align 


-Wwrite-strings 


-Wconversion 


-Waggregate-return 


-Wstrict-prototypes 


-Wmissing-prototypes 


-Wmissing-declarations 


-Wredundant -decls 


-Wnested-externs 
-Wenum-clash 
-Woverloaded-virtual 


Warn about certain constructs that behave differently in traditional and AN SI C: 


M acro arguments occurring within string constants in the macro body. T hese would substitute 
the argument in traditional C, but are part of the constant in ANSI C. 


A function declared external in one block and then used after theend of theblock. 

A switch statement has an operand of type long. 

Warn whenever a local variable shadows another local variable. 

Warn whenever two distinct identifiers match in the first | en characters. This may help you 
prepare a program that will compile with certain obsolete, brain-damaged compilers. 

Warn about anything that depends on the size of a function type or of void. GNU C assigns 
these types a size of 1, for convenience in calculations with void pointers and pointers to 
functions. 

W arn whenever a pointer is cast so as to remove a type qualifier from the target type. For 
example, warn if a const char is cast to an ordinary char. 


Warn whenever a pointer is cast such that the required alignment of the target is increased. For 
example, warn if achar is cast to an int on machines where integers can only be accessed at 
two- or four-byte boundaries. 

Give string constantsthetype const char[ |ength ] So that copying the address of one into a 
non-const char pointer will get a warning. T hese warnings will help you find at compile time 
code that can try to write into a string constant, but only if you have been very careful about 
using const in declarations and prototypes. O therwise, it will just be a nuisance thisis why we 
did not make -wa11 request these warnings. 

W arn if a prototype causes a type conversion that is different from what would happen to the 
same argument in the absence of a prototype. T hisincludes conversions of fixed point to 
floating and vice versa, and conversions changing the width or signedness of afixed point 
argument except when the same as the default promotion. 

W arn if any functions that return structures or unions are defined or called. (In languages 
where you can return an array, this also elicits a warning.) 

Warn if afunction is declared or defined without specifying the argument types. (An old-style 
function definition is permitted without a warning if preceded by a declaration which specifies 
the argument types.) 

W arn if a global function is defined without a previous prototype declaration. This warning is 
issued even if the definition itself provides a prototype. Theaim is to detect global functions 
that fail to be declared in header files. 

Warn if a global function is defined without a previous declaration. Do so even if the definition 
itself provides a prototype Usethis option to detect global functions that are not declared in 
header files. 

Warn if anything is declared more than once in the same scope, even in cases where multiple 
declaration is valid and changes nothing. 


W arn if an extern declaration is encountered within an function. 
Warn about conversion between different enumeration types (C ++ only). 


(C ++only.) In a derived class, the definitions of virtual functions must match the type signature 
of a virtual function declared in the base class. U se this option to request warnings when a 
derived class declares a function that may bean erroneous attempt to definea virtual function; 
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-Winline 


-Werror 


DEBUGGING OPTIONS 


that is, warn when there is a function with the same nameas a virtual function in the base class, 
but with a type signature that doesn’t match any virtual functions from the base class. 

Warn if afunction cannot be inlined, and athe it was declared as inline or else the -finline- 
functions option was given. 

Treat warnings as errors, abort compilation after any warning. 


GNU CC has various special options that are used for debugging athe your program or gcc: 


-g 


Produce debugging information in the operating system's native format (stabs, COFF, XCOFF, 
or DWARF). GDB (the GNU debugger) can work with this debugging information. 

On mos sysens that use stabs format, -g enables use of extra debugging information that only GDB 
can use; this extra information makes debugging work better in GDB but will probably make 
other debuggers crash or refuse to read the program. If you want to control for certain whether 
to generate the extra information, use -gstabs, -gstabs, -gxcoff+, -gxcoff, -gdwarf+, OF -gdwarf. 
Unlike most other C compilers, GNU CC allows you to use -g with -o. The shortcuts taken by 
optimized code may occasionally produce surprising results: Some variables you declared may 
not exist at all; flow of control may briefly move where you did not expect it; some statements 
may not be executed because they compute constant results or their values were already at hand; 
some statements may execute in different places because they were moved out of loops. 

N everthdless, it proves possible to debug optimized output. T his makes it reasonable to use the 
optimizer for programs that might have bugs. 





The following options are useful when GNU CC is generated with the capability for more than one debugging format. 


-ggdb 


-gstabs 


-gstabs+ 


-gcotf 


-gxcof 


-gxcofft+ 


-gdwar 





-gdwarf+ 


-gdwarfl evel 


Produce debugging information in the native format (if that is supported), including GDB 
extensions if at all possible 
Produce debugging information in stabs format (if that is supported), without GD B exten- 
sions. Thisis the format used by DBX on most BSD systems. 

Produce debugging information in stabs format (if that is supported), using GN U extensions 
understood only by the GN U debugger (GD B). The use of these extensions is likely to make 
other debuggers crash or refuse to read the program. 

Produce debugging information in COFF format (if that is supported). T his is the format used 
by SD B on most System V systems prior to System V Release 4. 

Produce debugging information in XCOFF format (if that is supported). T his is the format 
used by the D BX debugger on IBM RS/6000 systems. 

Produce debugging information in XCOFF format (if that is supported), using GNU 
extensions understood only by the GN U debugger (GD B). T he use of these extensions is likely 
to make other debuggers crash or refuse to read the program. 

Produce debugging information in DWARF format (if that is supported). T his is the format 
used by SDB on most Systen V Release 4 systems. 

Produce debugging information in DWARF format (if that is supported), using GN U 
extensions understood only by the GN U debugger (GD B). T he use of these extensions is likely 
to make other debuggers crash or refuse to read the program. 

-glevel 

-ggdbl evel 

-gstabsl evel 

-gcoffl evel -gxcoffl evel 














Request debugging information and also use! eve! to specify how much information. The 
default level is 2. 

Level 1 produces minimal information, enough for making backtraces in parts of the program 
that you don’t plan to debug. T his includes descriptions of functions and external variables, but 
no information about local variables and no line numbers. 


-dietters 





-fpretend-float 


-save-temps 


-print-file-name=l i brary 


-print-libgcc-file-name 


-print-prog-name=program 
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Level 3 includes extra information, such as all the macro definitions present in the program. 
Some debuggers support macro expansion when you use -g3. 


Generate extra code to write profile information suitable for the analysis program prof. 
Generate extra code to write profile information suitable for the analysis program gprof. 


Generate extra code to write profile information for basic blocks, which will record the number 
of times each basic block is executed. T his data could be analyzed by a program like tcov. N ote, 
however, that the format of the data is not what tcov expects. Eventually, GNU gprof should 
be extended to process this data. 


Says to make debugging dumps during compilation at times specified by! etters. Thisis used 
for debugging the compiler. T he filenames for most of the dumps are made by appending a 
word to the source filename (for example, foo.c.rtl OF foo.c. jump). 


Dump all macro definitions at the end of preprocessing, and write no output. 

Dump all macro names, at the end of preprocessing. 

Dump all macro definitions at the end of preprocessing, in addition to normal output. 

Dump debugging information during parsing, to standard error. 

Dump afte RTL generation, to file. rt1. 

Just generate RTL for afunction instead of compiling it. Usually used with r. 

Dump after first jump optimization, to file . jump. 

Dump after CSE (including the jump optimization that sometimes follows CSE), tofile . cse. 
Dump after loop optimization, to file . Loop. 


Dump after the second CSE pass (including the jump optimization that sometimes follows 
CSE), tofile . cse2. 


Dump after flow analysis, tofile . flow. 
Dump after instruction combination, to 
Dump after the first instruction scheduling pass, tofile . sched. 

Dump after local register allocation, tofile . 1reg. 

Dump after global register allocation, tofile . greg. 

Dump after the second instruction scheduling pass, to file .sched2. 

Dump after last jump optimization, tofile .jump2. 

Dump after ddayed branch scheduling, tofile .dbr. 

Dump after conversion from registers to stack, tofile .stack. 

Produce all the dumps listed previously. 

Print statistics on memory usage, at the end of therrun, to standard error. 

Annotate the assembler output with a comment indicating which pattern and alternative was 
used. 

When running across-compiler, pretend that the target machine uses the same floating-point 
format as the host machine T his causes incorrect output of the actual floating constants, but 
the actual instruction sequence will probably be the same as GNU CC would make when 
running on the target machine 

Store the usual temporary intermediate files permanently; place then in the current directory 
and name them based on the source file Thus, compiling foo.c with -c -save-temps would 
produce files foo.cpp and foo.s, as Well aS foo.o. 

Print the full absolute name of the library file! i brary would be used when linking, and do not 
do anything else. With thisoption, GNU CC doesnot compile or link anything; it just prints 
the filename 

Same as -print-file-name=libgcc.a. 

Like -print-file-name, but searches for a program such as cpp. 


e . combine. 
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OPTIMIZATION OPTIONS 


T hese options control various sorts of optimizations: 


-0, -01 


-02 


-03 


-00 


O ptimize O ptimizing compilation takes somewhat more time, and alot morememory for a 
large function. 

W ithout -o, the compiler’s goal is to reduce the cost of compilation and to make debugging 
produce the expected results. Statements are independent: If you stop the program with a 
breakpoint between statements, you can then assign a new value to any variable or change the 
program counter to any other statement in the function and get exactly the results you would 
expect from the source code. 

Without -o, only variables declared register are allocated in registers. T he resulting compiled 
code is alittle worse than produced by PCC without -o. 

With -o, the compiler tries to reduce code size and execution time. 

W hen you specify -o, the two options -fthread-jumps and -fdefer-pop are turned on. On 
machines that have delay slots, the -fdelayed-branch option is turned on. For those machines 
that can support debugging even without a frame pointer, the -fomit-frame-pointer option is 
turned on. On some machines other flags may also be turned on. 

Optimize even more N early all supported optimizations that do not involve a space-speed 
tradeoff are performed. Loop unrolling and function inlining are not done for example As 
compared to -o, this option increases both compilation time and the performance of the 
generated code 

O ptimize yet more. T his turns on everything -02 does, along with also turning on -finline- 
functions. 

Do not optimize 

If you use multiple -o options, with or without levd numbers, the last such option is the one 
that is effective 


O ptions of the form -+ f! ag specify machine independent flags. M ost flags have both positive and negative forms; the 
negative form of -ffoo would be -fno-foo. The following list shows only one form— the one which is not the default. You 
can figure out the other form by either removing no- or adding it. 


-ffloat-store 


-fmemorize-lookups 
-fsave-memorized 


Do not store floating-point variables in registers. T his prevents undesirable excess precision on 
machines such as the 68000 where the floating registers (of the 68881) keep more precision 
than a double is supposed to have. 

For most programs, the excess precision does only good, but a few programs rely on the precise 
definition of IEEE floating point. Use -ffloat-store for such programs. 

Use heuristics to compile faster (C ++ only). T hese heuristics are not enabled by default, 

since they are only effective for certain input files. O ther input files compile more slowly. 

The first time the compiler must build acall to amember function (or reference to a data 
member), it must (1) determine whether the class implanents member functions of that name; 
(2) resolve which member function to call (which involves figuring out what sorts of type 
conversions need to be made); and (3) check the visibility of the member function to the caller. 
All of this adds up to Sower compilation. N ormally, the second time acall is made to that 
member function (or reference to that data membe), it must go through the same lengthy 
process again. T his means that code like this: 

cout << "This " << p << "has"<< \ << " legs.\n" 

makes six passes through all three steps. By using a software cache a hit significantly reduces 
this cost. Unfortunatdy, using the cache introduces another layer of mechanisms which must 
beimplemented, and so incursits own overhead. -fmemorize- lookups enables the software 
cache 

Because access privileges (visibility) to menbers and member functions may differ from one 
function context to the next, g++ may need to flush the cache. W ith the -fmemorize-lookups 
flag, the cache is flushed after every function that is compiled. T he -fsave-memorized flag 


-fno-default-inline 


-fno-defer-pop 


-fforce-mem 


-fforce-addr 


-fomit-frame-pointer 


-finline-functions 


-fcaller-saves 


-fkeep-inline-functions 


-fno-function-cse 


-fno-peephole 
-ffast-math 
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enables the same software cache, but when the compiler determines that the context of the last 
function compiled would yield the same access privileges of the next function to compile it 
preserves the cache. T his is most helpful when defining many member functions for the same 
class: with the exception of member functions which are friends of other classes, each member 
function has exactly the same access privileges as every other, and the cache need not be flushed. 
Don’t make member functions inline by default merely because they are defined inside the class 
scope (C+ only). 

Always pop the arguments to each function call as soon as that function returns. For machines 
which must pop arguments after a function call, the compiler normally lets arguments 
accumulate on the stack for several function callsand pops them all at once. 

Force memory operands to be copied into registers before doing arithmetic on them. This may 
produce better code by making all memory references potential common subexpressions. When 
they are not common subexpressions, instruction combination should eliminate the separate 
register-load. | am interested in hearing about the difference this makes. 

Force memory address constants to be copied into registers before doing arithmetic on them. 
This may produce better code just as -fforce-mem may. | am interested in hearing about the 
difference this makes. 


Don’t keep the frame pointer in a register for functions that don’t need one. This avoids the 
instructions to save, set up and restore frame pointers; it also makes an extra register available in 
many functions. It also makes debugging impossible on most machines. 

On somemachine, such as the VAX, this flag has no effect because the standard calling 
sequence automatically handles the frame pointer and nothing is saved by pretending it doesn’t 
exist. The machine-description macro FRAME_POINTER_REQUIRED Controls whether a target 
machine supports this flag. 

Integrate all simple functions into their callers. The compiler heuristically decides which 
functions are simple enough to be worth integrating in this way. 

If all calls to a given function areintegrated, and the function is declared static, then gcc 
normally does not output the function as assembler code in its own right. 

Enable values to be allocated in registers that will be clobbered by function calls, by emitting 
extra instructions to save and restore the registers around such calls. Such allocation is done 
only when it seems to result in better code than would otherwise be produced. 

This option is enabled by default on certain machines, usually those which have no call- 
preserved registers to use instead. 

Even if all calls to agiven function are integrated, and the function is declared static, 
nevertheless output a separate runtime callable version of the function. 

Do not put function addresses in registers; make each instruction that calls a constant function 
contain the function’s address explicitly. 

This option results in less efficient code, but some strange hacks that alter the assembler output 
may be confused by the optimizations performed when this option is not used. 

Disable any machine-specific peephole optimizations. 

This option allows gcc to violate some AN SI or IEEE specifications in the interest of optimiz- 
ing code for speed. For example, it allows the compiler to assume arguments to the sqrt 
function are nonnegative numbe’s. 

This option should never be turned on by any -o option because it can result in incorrect 
output for programs which depend on an exact implementation of IEEE or AN SI rules 
specifications for math functions. 





The following options control specific optimizations. T he -o2 option turns on all of these optimizations except -funro11- 
loops and -funroll-all-loops 


The -o option usually turns on the -fthread-jumps and -fdelayed-branch options, but specific machines may change the 


default optimizations. 
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You can use the following flags in the rare cases when fine-tuning of optimizations to be performed is desired: 


-fstrength-reduce 
-fthread-jumps 


unroll-loops 


unroll-all-loops 


cse-follow- jumps 


cse-skip-blocks 


rerun-cse-after-loop 





elide-constructors 


-fexpensive-optimizations 


-fdelayed-branch 


-fschedule-insns 


-fschedule-insns2 


TARGET OPTIONS 


Perform the optimizations of loop strength reduction and dimination of iteration variables. 
Perform optimizations where we check to see if ajump branches to a location where another 
comparison subsumed by the first is found. If so, the first branch is redirected to either the 
destination of the second branch or a point immediately following it, depending on whether 
the condition is known to be true or false. 

Perform the optimization of loop unrolling. T his is only done for loops whose number of 
iterations can be determined at compile time or runtime 

Perform the optimization of loop unrolling. This is done for all loops. T his usually makes 
programs run more slowly. 

In common subexpression elimination, scan through jump instructions when the target of the 
jump isnot reached by any other path. For example, when CSE encounters an if statenent 
with an else clause, CSE will follow the jump when the condition tested is false 

Thisis similar to -fcse-follow-jumps, but causes C SE to follow jumps which conditionally skip 
over blocks. When CSE encounters a simple if statement with no else clause, -fcse-skip- 
blocks Causes CSE to follow thejump around the body of the ir. 

Rerun common subexpression elimination after loop optimizations has been performed. 

Elide constructors when this seems plausible (C ++ only). With this flag, GN U C ++ initializes y 
directly from the call to foo without going through a temporary in the following code 

A foo (); A y =foo (); 

Without this option, GNU C -++first initializes y by calling the appropriate constructor for type 
A; then assigns the result of foo to a temporary; and, finally, replaces the initial value of y with 
the temporary. 

The default behavior (-fno-elide-constructors) is specified by the draft AN SI C ++ standard. If 
your program’s constructors have side effects, using -felide-constructors Can make your 
program act differently, since some constructor calls may be omitted. 

Perform anumber of minor optimizations that are rdativedy expensive. 

If supported for the target machine, attenpt to reorder instructions to exploit instruction slots 
available after delayed branch instructions. 

If supported for the target machine, attenpt to reorder instructions to eliminate execution stalls 
due to required data being unavailable. T his hdps machines that have slow floating point or 
memory load instructions by allowing other instructions to be issued until the result of the load 
or floating point instruction is required. 

Similar to -fschedule-insns, but requests an additional pass of instruction scheduling after 
register allocation has been done This is especially useful on machines with a relatively small 
number of registers and where memory load instructions take more than one cycle 


By default, GNU CC compiles code for the same type of machine that you are using. 


H owever, it can also be installed as a cross-compiler, to compile for some other type of machine In fact, several different 
configurations of GNU CC, for different target machines, can be installed side by side. Then you specify which one to use 


with the -b option. 


In addition, older and newer versions of GNU CC can be installed side by side. O neof them (probably the newest) will be 
the default, but you may sometimes want to use another. 


-b machine 


Theargument machine specifies the target machine for compilation. This is useful when you 
haveinstalled GNU CC asacross-compiler. 

The value to usefor machine isthe same as was specified as the machine type when configuring 
GNU CC asacross-compiler. For example, if a cross-compiler was configured with configure 


i386v, meaning to compile for an 80386 running Systen V, then you would specify -b i386v to 
run that cross compiler. 

When you do not specify -b, it normally means to compile for the same type of machine that 
you are using. 


-V version Theargument version specifies which version of GNU CC to run. Thisis useful when multiple 
versions are installed. For example, version might be 2.0, meaning to run GNU CC version 
2.0. 


The default version, when you do not specify -v, is controlled by the way GNU CC is installed. 
Normally, it will be aversion that is recommended for general use. 


MACHINE-DEPENDENT OPTIONS 


Each of the target machine types can haveits own special options, starting with -m, to choose among various hardware 
moddss or configurations— for example, 68010 versus 68020, floating coprocessor or none A single installed version of the 
compiler can compile for any model or configuration, according to the options specified. 


Some configurations of the compiler also support additional special options, usually for command-line compatibility with 
other compilers on the same platform. 


T hese are the -m options defined for the 68000 series: 


-m68000 Generate output for a 68000. T hisis the default when the compiler is configured for 68000- 

-mc68000 based systems. 

-m68020 Generate output for a 68020 (rather than a 68000). Thisis the default when the compiler is 

-mc68020 configured for 68020-based systems. 

-m68881 Generate output containing 68881 instructions for floating point. T his is the default for most 
68020-based systems unless -nfp was specified when the compiler was configured. 

-m68030 Generate output for a 68030. T hisis the default when the compiler is configured for 68030- 
based systems. 

-m68040 Generate output for a 68040. T hisis the default when the compiler is configured for 68040- 
based systems. 

-m68020-40 Generate output for a 68040, without using any of the new instructions. This results in code 
which can run rdativey efficiently on either a 68020/68881 or a 68030 or a 68040. 

-mfpa Generate output containing Sun FPA instructions for floating point. 

-msoft-float Generate output containing library calls for floating point. 


The requisite libraries are not part of GNU CC. Normally, the facilities of the machine's usual C compiler are used, but 
thiscan’t bedonedirectly in cross-compilation. You must makeyour own arrangements to provide suitable library func- 
tions for cross-compilation. 


-mshort Consider type int to be 16 bits wide, like short int. 

-mnobitfield Do not use the bit-fidd instructions. -meseoo implies -mnobitfield. 

-mbitfield Do use the bit-field instructions. -meso20 implies -mbitfield. Thisis the default if you use the 
unmodified sources. 

-mrtd Usea different function-calling convention, in which functions that take a fixed number of 


arguments return with the rtd instruction, which pops thar arguments while returning. T his 
saves one instruction in the caller since there is no need to pop the arguments thee. 

This calling convention is incompatible with the one normally used on UNIX, so you cannot 
use it if you need to call libraries compiled with the UNIX compile. 
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Also, you must provide function prototypes for all functions that take variable numbers of 
arguments (including printf ); otherwise, incorrect code will be generated for calls to those 
functions. 

In addition, seriously incorrect code will result if you call a function with too many arguments. 
(N ormally, extra arguments are harmlessly ignored.) 

The rtd instruction is supported by the 68010 and 68020 processors, but not by the 68000. 


T hese -m options are defined for the VAX: 


-munix Do not output certain jump instructions (aobleq and so on) that the UNIX assembler for the 
VAX cannot handleacross long ranges. 

-mgnu Do output those jump instructions, on the assumption that you will assemble with the G NU 
assembler. 

-mg Output code for g-format floating-point numbers instead of d-format. 


T hese -m switches are supported on the sparc: 


-mfpu Generate output containing floating-point instructions. T his is the default. 
-mhard-float 
-mno-fpu Generate output containing library calls for floating point. 


-msoft-float 


Thereisno GNU floating-point library for SPARC. Normally, the facilities of the machine's usual C compiler are used, 
but this cannot be done directly in cross-compilation. You must make your own arrangements to provide suitablelibrary 
functions for cross-compilation. 


-msoft-float Changes the calling convention in the output file: therefore it isonly useful if you compile all 
of a program with this option. 

-mno-epilogue With -mepilogue (the default), the compiler always emits code for function exit at the end of 

-mepilogue each function. Any function exit in the middle of the function (such as a return statement in C) 


will generate a jump to the exit code at the end of the function. W ith -mno-epilogue, the 
compiler tries to emit exit code inline at every function exit. 


-mno-v8 T hese three options select variationson theSPARC architecture. By default (unless specifically 
-mv8 configured for the Fujitsu SPARClite), gcc generates code for the v7 variant of the SPARC 
msparclite architecture. 


-mv8 will give you SPARC v8 code The only difference from v7 code is that the compiler emits 
the integer multiply and integer divide instructions that exist in SPARC v8 but not in SPARC v7. 


-msparclite will give you SPARClite code This adds the integer multiply, integer divide step 
and scan (ffs) instructions that exist in SPARC lite but not in SPARC v7. 


-mcypress T hese two options select the processor for which the code is optimized. 


-msupersparc With -mcypress (the default), the compiler optimizes code for the C ypress CY7C 602 chip, as 
used in the SparcStation and SparcServer 3xx series. T hisis also appropriate for the older 
SparcStation 1, 2, 1PX, and so on. 


With -msuperspare the compiler optimizes code for the SuperSparc cpu, as used in the 
SparcStation 10, 1000, and 2000 series. T his flag also enables use of the full SPARC v8 
instruction set. 

T hese -m options are defined for the C onvex: 


-met Generate output foraC1. Thisis the default when the compiler is configured for aC1. 
-me2 Generate output for aC 2. Thisis the default when the compiler is configured for aC2. 
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-margcount Generate code which puts an argument count in the word preceding each argument list. Some 
nonportable C onvex and VAX programs need this word. (D ebuggers don’t, except for 
functions with variable length argument lists; this information isin the symbol table.) 


-mnoargcount Omit the argument count word. This is the default if you use the unmodified sources. 

These -m options are defined for the AM D Am29000: 

-mdw Generate code that assumes the D W bit is set, that is, that byte and half-word operations are 
directly supported by the hardware. T his is the default. 

-mnodw Generate code that assumes the D W bit is not set. 

-mbw Generate code that assumes the systen supports byte and halfword write operations. This is the 
default. 

-mnbw Generate code that assumes the systems does not support byte and halfword write operations. 
This implies -mnoaw. 

-msmall Use asmall memory model that assumes that all function addresses are dther within asingle 


256K B segment or at an absolute address of less than 256K. T his allows the cali instruction to 
be used instead of a const, consth, calli Sequence 


-mlarge Do not assume that the cai1 instruction can be used; this is the default. 

-m29050 Generate code for theAm29050. 

-m29000 Generate code for the Am29000. T his is the default. 

-mkernel-registers Generate references to registers gré4-grgs instead of gr96- gri127. T his option can be used when 
compiling kernd code that wants a set of global registers digoint from that used by user-mode 
code. 

N ote that when this option is used, register names in -+ flags must use the normal, user-mode, 
names. 

-muser-registers Use the normal set of global registers, gro6- gr127. Thisis the default. 

-mstack-check Insert a call to msp check after each stack adjustment. T hisis often used for kernel code. 


T hese -m options are defined for M otorola 88K architectures: 


-m88000 Generate code that works well on both the m88100 and the m88110. 

-m88100 Generate code that works best for the m88100, but that also runs on the m88110. 

-m88110 Generate code that works best for the m88110, and may not run on the m88100. 

-midentify-revision Include an ident directive in the assembler output recording the source filename, compiler 
name and version, timestamp, and compilation flags used. 

-mno-underscores In assembler output, emit symbol names without adding an underscore character at the 
beginning of each name. T he default is to use an underscore as prefix on each name. 

-mcheck-zero-division Early moddss of the 88K architecture had problems with division by zero; in particular, many of 


-mno-check-zero-division them didn’t trap. Use these options to avoid including (or to include explicitly) additional code 
to detect division by zero and signal an exception. All gcc configurations for the 88K use 
-mcheck-zero-division by default. 

-mocs-debug-info Include (or omit) additional debugging information (about registers used in each stack frame) 

-mno-ocs-debug-info as specified in the 880 pen O bject Compatibility Standard, O CS. T his extra information is not 
needed by GDB. Thedefault for DG/UX, SVr4, and D elta 88 SVr3.2 is to include this 
information; other 88K configurations omit this information by default. 

-mocs-frame-position Force (or do not require) register values to be stored in a particular place in stack frames, as 

-mno-ocs-frame-position  specifiedinOCS. TheDG/UX, D ata88 SVr3.2, and BCS configurations use -mocs-frame- 
position; other 88K configurations have the default -mno-ocs- frame-position. 

-moptimize-arg-area Control how to store function arguments in stack frames. -moptimize-arg-area Saves space, but 

-mno-optimize-arg-area may break some debuggers (not GD B). -mno-optimize-arg-area Conforms better to standards. 
By default gcc does not optimize the argument area. 
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-mshort-data-num Generate smaller data references by making then rdative to re, which allows loading a value 
using a single instruction (rather than the usual two). You control which data references are 
affected by specifying num with this option. For example, if you specify -mshort-data-512, 
then the data references affected are those involving displacements of less than 512 bytes. 
-mshort-data-num iS not effective for num greater than 64K. 

-mserialize-volatile Do, or do not, generate code to guarantee sequential consistency of volatile memory references. 

-mno-serialize-volatile | GNU CC always guarantees consistency by default, for the preferred processor submodel. H ow 
this is done deoends on the submodel. 

The m88100 processor does not reorder memory references and so always provides sequential 
consistency. If you use -mgs10e,G NU CC does not generate any special instructions for 
sequential consistency. 

The order of memory references made by the m88110 processor does not always match the 
order of the instructions requesting those references. In particular, aload instruction may 
execute before a preceding store instruction. Such reordering violates sequential consistency of 
volatile memory references, when there are multiple processors. W hen you use -m88eee or 
-mg8110, GNU CC generates special instructions when appropriate to force execution in the 
proper order. 

The extra code generated to guarantee consistency may affect the performance of your 
application. If you know that you can safely forgo this guarantee you may use the option 
-mno-serialize-volatile. 

If you use the -mss1e0 option but require sequential consistency when running on the m88110 
processor, you should use -mserialize-volatile. 

-msvr4, -msvr3 Turn on (-msvr4) or off (-msvr3) compiler extensions rdated to System V release 4 (SV r4). This 
controls the following: 

W hich variant of the assembler syntax to emit (which you can select independently using 
-mversion-03. 00). 

-msvr4 makes the C preprocessor recognize #pragma weak. 

-msvr4 Makes gcc issue additional declaration directives used in SVr4, 

-msvr3 is the default for all m88K configurations except the SV r4 configuration. 


-mtrap-large-shift Include code to detect bit-shifts of more than 31 bits; respectively, trap such shifts or anit code 

-mhandle-large-shift to handle then propelly. By default, gec makes no special provision for large bit shifts. 

-muse-div-instruction Very early modds of the 88K architecture didn’t have a divide instruction, so gcc avoids that 
instruction by default. Use this option to specify that it’s safe to use the divide instruction. 

-mversion-03.00 In the D G/U X configuration, there are two flavors of SVr4. This option modifies -msvr4 to 
select whether the hybrid-C O FF or real-ELF flavor is used. All other configurations ignore this 
option. 

-mwarn-passed-structs Warn when a function passes a struct aS an argument or result. Structure passing conventions 


have changed during the evolution of the C language, and are often the source of portability 
problems. By default, gcc issues no such warning. 


T hese options are defined for the|BM RS6000: 


-mfp-in-toc Control whether or not floating-point constants go in the table of contents (TO C), a table of 

-mno-fp-in-toc all global variable and function addresses. By default gcc puts floating-point constants there if 
theT OC overflows, -mno-fp-in-toc will reduce thesize of the TOC, which may avoid the 
overflow. 

T hese -m options are defined for the|BM RT PC: 

-min-line-mul Use an inline code sequence for integer multiplies. Thisis the default. 

-mcall-lib-mul Call imuiss for integer multiples. 

-mfull-fp-blocks Generate full-size floating-point data blocks, including the minimum amount of scratch space 


recommended by IBM . T hisis the default. 
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-mminimum-fp-blocks Do not include extra scratch spacein floating-point data blocks. T his results in smaller code, 
but slower execution, since scratch space must be allocated dynamically. 
-mfp-arg-in-fpregs Use a calling sequence incompatible with the IBM calling convention in which floating-point 


arguments are passed in floating-point registers. N ote that varargs.h and stdargs-h will not 
work with floating-point operands if this option is specified. 

-mfp-arg-in-gregs Use the normal calling convention for floating-point arguments. T his is the default. 

-mhe-struct-return Return structures of more than one word in memory, rather than in a register. T his provides 
compatibility with the M etaW areHighC (hc) compiler. Use -fpcc-struct-return for compat- 
ibility with the Portable C Compiler (PCC). 

-mnohc-struct-return Return some structures of more than one word in registers, when convenient. T hisis the 
default. For compatibility with the BM -supplied compilers, use either -fpcc-struct-return or 
-mhc-struct-return 


T hese -m options are defined for the MIPS family of computers: 


-mcpu=c pu- type Assume the defaults for the machine type cpu- type when scheduling instructions. T he default 
cpu-type is default, which picks the longest cycles times for any of the machines, in order that 
the code run at reasonable rates on all MIPS CPUs, Other choices for cpu- type are r2000, r3000, 
r4000,and reeeo. While picking a specific cpu- type will schedule things appropriately for that 
particular chip, the compiler will not generate any code that does not meet level 1 of the MIPS 
ISA (instruction set architecture) with-out the -mips2 or -mips3 switches being used. 


-mips2 Issue instructions from leved 2 of the MIPSISA (branch likey, square root instructions). 
The -mcpu=r4000 Or -mcpu=r6000 switch must be used in conjunction with -mips2. 

-mips3 Issue instructions from leva 3 of the MIPS 1SA (64-bit instructions). The -mcpu=r4000 switch 
must be used in conjunction with -mips2. 

-mint64, -mlong64 T hese options don’t work at present. 

-mlonglong128 

-mmips-as Generate code for the M IPS assembler, and invoke mips-tfile to add normal debug informa- 


tion. Thisis the default for all platforms except for the O SF/1 reference platform, using the 
O SF/rose object format. If any of the -ggdb, -gstabs, Or -gstabs+ switches are used, the mips- 
tfile program will encapsulate the stabs within MIPS ECOFF. 


-mgas Generate code for the GN U assembler. This is the default on the O SF/1 reference platform, 
using the O SF/rose object format. 
-mrnames, -mno-rnames The -mrnames switch says to output code using the MIPS software names for the registers, 


instead of the hardware names (for example, ao instead of $4). TheGNU assembler does not 
support the -mrnames switch, and the MIPS assembler will be instructed to run the MIPSC 
preprocessor over the source file. T he -mno-rnames switch is default. 

-mgpopt, -mno-gpopt The -mgpopt switch says to write all of the data declarations before the instructions in the text 
section, to all the MIPS assembler to generate one word memory references instead of using 
two words for short global or static data items. Thisis on by default if optimization is selected. 

-mstats, -mno-stats For each noninline function processed, the -mstats switch causes the compiler to anit one line 
to the standard error file to print statistics about the program (number of registers saved, stack 
size, and so on). 


-mmemcpy, -mno-memcpy The -mmemcpy switch makesall block moves call the appropriate string function (memcpy or 
beopy) instead of possibly generating inline code. 

-mmips-tfile The -mno-mips-tfile switch causes the compiler to not post-process the object file with the 

-mno-mips-tfile mips-tfile program, after the MIPS assembler has generated it to add debug support. If mips- 


tfile isnot run, then no local variables will be available to the debugger. In addition, stage2 
and stage3 objects will have the temporary filenames passed to the assanbler embedded in the 
object file which means the objects will not compare the same. 


-msoft-float Generate output containing library calls for floating point. 
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The requisite libraries are not part of GNU CC. Normally, the facilities of the machine's usual C compiler are used, but 
thiscan’t bedonedirectly in cross-compilation. You must makeyour own arrangements to provide suitable library func- 
tions for cross-compilation. 


-mhard-float Generate output containing floating point instructions. This is the default if you use the 
unmodified sources. 
-mfp64 Assume that the Fr bit in the status word is on, and that there are 32 64-bit floating-point 


registers, instead of 32 32-bit floating-point registers. You must also specify the -mcpu=r40e0 and 
-mips3 Switches. 


-mfp32 Assume that there are 32 32-bit floating-point registers. This isthe default. 

-mabicalls Emit (or do not emit) the .abicalls, .cpload, and .cprestore pseudo operations that some 

-mno-abicalls System V .4 ports use for position-indeoendent code. 

-mhalf-pic The -mhalf-pic switch says to put pointers to extern references into the data section and load 

-mno-half-pic them up, rather than put the references in the text section. This option does not work at 
present. 

-Gnum Put global and static itans less than or equal to num bytes into the small data or bss sections 


instead of the normal data or bss section. T his allows the assembler to emit one-word memory 
reference instructions based on the global pointer (gp or $28), instead of the normal two words 
used. By default, num is 8 when the M IPS assembler is used, and @ when the GNU assembler is 
used. The -Gnum switch is also passed to the assembler and linker. All modules should be 
compiled with thesame -cnum value 

-nocpp Tell the MIPS assembler to not run its preprocessor over user assembler files (with an .s suffix) 
whe assembling them. 


T hese -m options are defined for the Inte 80386 family of computers: 


-m486, -mno-486 Control whether or not code is optimized for a 486 instead of a386. Code generated for a 486 
will run on a386 and vice versa. 
-msoft-float Generate output containing library calls for floating point. 


The requisite libraries are not part of GNU CC. Normally, the facilities of the machine's usual C compiler are used, but 
thiscan’t bedonedirectly in cross-compilation. You must make your own arrangements to provide suitable library func- 
tions for cross-compilation. 


On machines where a function returns floating point results in the 80387 register stack, some 
floating-point opcodes may be emitted even if -msoft-float is used. 

-mno-fp-ret -in-387 Do notusetheFPU registers for return values of functions. 
Theusual calling convention has functions return values of types float and double in an FPU 
register, even if thereis no FPU. The idea is that the operating system should emulate an FPU. 


The option -mno-fp-ret-in-387 Causes such values to be returned in ordinary CPU registers 
instead. 


T hese -m options are defined for the H PPA family of computers: 


-mpa-risc-1-0 Generate code for aPA 1.0 processor. 
-mpa-risc-1-1 Generate code for aPA 1.1 processor. 


-mkernel 


-mshared-libs 


-mno-shared- libs 


-mlong-calls 


-mdisable-fpregs 


-mdisable- indexing 


-mtrailing-colon 
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Generate code which is suitable for use in kernels. Specifically, avoid aaa instructions in which 
oneof the arguments istheD P register; generate adail instructions instead. T his avoids a rather 
serious bug in the H P-U X linker. 

Generate code that can be linked against H P-U X shared libraries. T his option is not fully 
functioning yet, and is not on by default for any PA target. Using this option can cause 
incorrect code to be generated by the compiler. 

Don’t generate code that will be linked against shared libraries. Thisis the default for all PA 
targets. 

Generate code which allows calls to functions greater than 256K away from the caller when the 
caller and callee arein the same source file. D o not turn this option on unless code refuses to 
link with branch out of range errors from the linke. 

Prevent floating-point registers from being used in any manne”. T his is necessary for compiling 
kernds that perform lazy context switching of floating-point registers. If you use this option 
and attempt to perform floating-point operations, the compiler will abort. 

Prevent the compiler from using indexing address modes. T his avoids some rather obscure 
problems when compiling M1G-generated code under MACH. 


Add acolon to the end of label definitions (for ELF assanblers). 


T hese -m options are defined for the | nte 80960 family of computers: 


-mcpu-type 


-mnumerics 
-msoft-float 
-mleaf-procedures 
-mno-leaf-procedures 


-mtail-call 
-mno-tail-call 


-mcomplex-addr 
-mno-complex-addr 


-mcode-align 
-mno-code-align 
-mic-compat 
-mic2.0-compat 
-mic3.0-compat 
-masm-compat 
-mintel-asm 
-mstrict-align 
-mno-strict-align 


-mold-align 


Assume the defaults for the machine type cpu- type for instruction and addressing-mode 
availability and alignment. The default cpu-type iS kb; other choices are ka, mc, ca, cf, sa, aNd sb. 
The -mnumerics option indicates that the processor does support floating-point instructions. 
The -msoft-float option indicates that floating-point support should not be assumed. 

Do (or do not) attempt to alter leaf procedures to be callable with theba! instruction as well as 
call. This will result in more efficient code for explicit calls when theba! instruction can be 
substituted by the assembler or linker, but less efficient code in other cases, such as calls via 
function pointers, or using a linker that doesn’t support this optimization. 

Do (or do not) make additional attempts (beyond those of the machine-independent portions 
of the compiler) to optimize tail-recursive calls into branches. You may not want to do this 
because the detection of cases where this is not valid isnot totally complete. T he default is 
-mno-tail-call 

Assume (or do not assume) that the use of a complex addressing modeisa win on thisimple 
mentation of the i960. Complex addressing modes may not be worthwhile on the K-series, but 
they definitely are on the C-series. The default is currently -mcomp1ex-addr for all processors 
except the CB and CC. 

Align code to 8-byte boundaries for faster fetching (or don’t bother). Currently turned on by 
default for C-series implementations only. 


Enable compatibility with iC 960 v2.0 or v3.0. 
Enable compatibility with the iC 960 assembler. 
Do not permit (do permit) unaligned accesses. 


Enable structure-alignment compatibility with Intel’s gcc release version 1.3 (based on gee 
1.37). Currently this is buggy in that #pragma align 1 is always assumed aswell, and cannot be 
turned off. 
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T hese -m options are defined for the DEC Alphaimplementations: 


-mno-soft-float 
-msoft-float 


-mfp-reg, -mno-fp-regs 


Use (do not use) the hardware floating-point instructions for floating-point operations. When 
-msoft-float is specified, functionsin 1ibgcc1.c will be used to perform floating-point 
operations. Unless they are replaced by routines that enulate the floating-point operations, or 
compiled in such a way as to call such emulations routines, these routines will issue floating- 
point operations. If you are compiling for an Alpha without floating-point operations, you 
must ensure that the library is built so as not to call them. 

N ote that Alpha implementations without floating-point operations are required to have 
floating-point registers. 
Generate code that uses (does not use) the floating-point register set. -mno-fp-regs implies 
-msoft-float. If the floating-point register set is not used, floating-point operands are passed in 
integer registers as if they were integers and floating-point results are passed in so instead of $fo. 
This is anonstandard calling sequence, so any function with a floating-point argument or 
return value called by code compiled with -mno-fp-regs must also be compiled with that 
option. 

A typical use of this option is building a kernel that does not use, and hence need not save and 
restore, any floating-point registers. 





T hese additional options are available on System V R dease 4 for compatibility with other compilers on those systems: 


-G On SVr4 systems, gcc accepts the option -c (and passes it to the system linker), for compatibil- 
ity with other compilers. H owever, we suggest you Use -symbolic Or -shared as appropriate, 
instead of supplying linker options on the gcc command line 

-Qy Identify the versions of each tool used by the compiler, in an .ident assembler directive in the 
output. 

-Qn Refrain from adding . ident directives to the output file (this is the default). 

-YP dirs Search the directories dirs, and no others, for libraries specified with -1. You can separate 
directory entriesin dirs from one another with colons. 

-Ym, dir Look in the directory dir to find the M 4 preprocessor. T he assembler uses this option. 

CODE GENERATION OPTIONS 


These machine independent options control the interface conventions used in code generation. 


M ost of them begin with -+. T hese options have both positive and negative forms; the negative form of -ffoo would be -fno- 
foo. In the following table, only one of the formsis listed— the one which is not the default. You can figure out the other 
form by ether removing no- or adding it. 


-fnonnull-objects 


-fpec-struct-return 


-freg-struct-return 


Assume that objects reached through references are not null (C ++ only). 

Normally, GNU C++makes conservative assumptions about objects reached through 
references. For example, the compiler must check that a is not null in code like the following: 
obj &a = g (); a.f (2); 

Checking that references of this sort have nonnull values requires extra code, however, and it is 
unnecessary for many programs. You can use -fnonnull-objects to omit the checks for null, if 
your program doesn’t require checking. 

Use the same convention for returning struct and union values that is used by the usual C 
compiler on your system. T his convention is less efficient for small structures, and on many 
machines it failsto be reentrant; but it has the advantage of allowing intercallability between 
gec-compiled code and pcc-compiled code 

Use the convention that struct and union values are returned in registers when possible This is 
more efficient for small structures than -fpcc-struct-return. 

If you specify nather -fpcc-struct-return Nor -freg-struct-return, GNU CC defaults to 
whichever convention is standard for the target. If there isno standard convention, GNU CC 
defaults to -fpcc-struct-return. 
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-fshort-enums Allocate to an enum type only as many bytes as it needs for the declared range of possible values. 
Specifically, the enum type will be equivalent to the smallest integer type that has enough room. 

-fshort-double Use the same size for double as for float. 

-fshared-data Requests that the data and non-const variables of this compilation be shared data rather than 


private data. T he distinction makes sense only on certain operating systems, where shared data 
is shared between processes running the same program, while private data exists in one copy per 
process. 

-fno-common Allocate even uninitialized global variables in the bss section of the object file, rather than 
generating them as common blocks. T his has the effect that if the same variable is declared 
(without extern) in two different compilations, you will get an error when you link then. The 
only reason this might be useful isif you want to verify that the program will work on other 
systems which always work this way. 

-fno-ident Ignore the #ident directive. 

-fno-gnu-linker Do not output global initializations (such as C ++ constructors and destructors) in the form 
used by the GNU linker (on systems where theGN U linker is the standard method of handling 
them). Use this option when you want to useanon-GN U linker, which also requires using the 
collect2 program to make sure the system linker includes constructors and destructors. 
(collect2 isincluded in the GNU CC distribution.) For systems that mug use collect2, the 
compiler driver gcc is configured to do this automatically. 

-finhibit-size-directive Don’t output a.size assembler directive or anything else that would cause trouble if the 

function is split in the middle, and the two halves are placed at locations far apart in memory. 

This option is used when compiling crtstuff.c; you should not need to useit for anything dse 

-fverbose-asm Put extra commentary information in the generated assembly code to make it more readable. 

This option is generally only of use to those who actually need to read the generated assembly 

code (perhaps while debugging the compiler itself). 





-fvolatile Consider all memory references through pointers to be volatile 

-fvolatile-global Consider all memory references to extern and global data items to be volatile. 

-fpic If supported for the target machines, generate position-independent code, suitable for usein a 
shared library. 

-fPIC If supported for the target machine, emit position-independent code, suitable for dynamic 
linking, even if branches need large displacements. 

-ffixed-reg Treat the register named reg as a fixed register; generated code should never refer to it (except 


perhaps as a stack pointer, frame pointer, or in some other fixed role). 


reg Must be thename of a register. Theregister names accepted are machine specific and are 
defined in the rEGISTER_NAMES macro in the machine description macro file 


This flag does not havea negative form, because it specifies a three-way choice 
-fcall-used-reg Treat the register named reg as an allocable register that is cobbered by function calls. It may 

be allocated for temporaries or variables that do not live across a call. Functions compiled this 

way will not save and restore the register reg. 

Use of this flag for a register that has a fixed pervasive role in the machine's execution model, 

such as the stack pointer or frame pointer, will produce disastrous results. 

This flag does not havea negative form, because it specifies a three-way choice 
-fcall-saved-reg T reat the register named reg as an allocable register saved by functions. It may be allocated even 

for temporaries or variables that live across a call. Functions compiled this way will save and 

restore the register reg if they use it. 

Use of this flag for a register that has a fixed pervasive role in the machine's execution model, 

such as the stack pointer or frame pointer, will produce disastrous results. 

A different sort of disaster will result from the use of this flag for a register in which function 

values may be returned. 

This flag does not havea negative form, because it specifies a three-way choice 
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PRAGM 


AS 


Two #pragma directives are supported for GNU C++to permit using the same header file for two purposes: as a definition of 
interfaces to a given object class, and as the full definition of the contents of that object class. 
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R/cc 

R/cpp 
Ricci 
R/cciplus 
R/collect 
R/libgec.a 


ib/crt[@1n].o 


R/ccrto 


ib/libc.a 


/include 
R /include 
R /gt++-include 





(C +only.) Use this directive in header files that define object classes, to save space in most of 
the object files that use those classes. N ormally, local copies of certain information (backup 
copies of inline member functions, debugging information, and the internal tables that 
implement virtual functions) must be kept in each object file that includes class definitions. You 
can use this pragma to avoid such duplication. When a header file containing #pragma 

interface iSincluded in acompilation, this auxiliary information will not be generated (unless 
the main input source file itself uses #pragma implementation). Instead, the object files will 
contain references to be resolved at link time 


(C ++only.) Use this pragma in amain input file. when you want full output from included 
header files to be generated (and made globally visible). The included header file, in turn, 
should use #pragma interface. Backup copies of inline member functions, debugging informa- 
tion, and the internal tables used to implanent virtual functions are all generated in implenen- 
tation files. 


If you use #pragma implementation with no argument, it applies to an include file with the same 
basename as your source file; for example, in allclass.cc, #pragma implementation by itself is 
equivalent to #pragma i-plementation "allclass.h". Usethe string argument if you want a 
single implementation file to include code from multiple header files. 


Thee is no way to split up the contents of a single header file into multiple implementation 
files. 


C source file 

C header (preprocessor) file 
Preprocessed C source file 

C ++ source file 

C ++ source file 

C ++ source file 

Objective-C source file 

Assembly language file 

O bject file 

Link edited output 

Temporary files 

Preprocessor 

Compiler for C 

Compiler for C ++ 

Linker front end needed on some machines 
gee Subroutine library 

Startup routine 

Additional startup routine for C ++ 
Standard C library; see intro(3) 
Standard directory for #include files 
Standard gcc directory for #include files 
Additional g++ directory for #include 


R iS usually /usr/local/lib/machine /version. 
R comes from the environment variable Tupp1R (default /usr/tmp if available; otherwise, /tmp.). 


gentopbm 


SEE ALSO 
cpp(1), as(1), 14(1), gab(1), adb(1), dbx(1), sdb(1) 
gcc, cpp, as, 1d, and gdb entriesin info. 


Usngand PortingGNU CC (for version 2.0), Richard M . Stallman; TheC Preprocesor, Richard M . Stallman; D ebugging 
with GDB: theGNU Source Levd D ebugge, Richard M. Stallman and Roland H. Pesch; Usngas theGNU Assembler, D ean 
Elsner, J ay Fenlason & friends; Id: the GNU Linker, Steve Chamberlain and Roland Pesch. 


BUGS 


For instructions on reporting bugs, see the GCC manual. 


COPYING 
Copyright 1991, 1992, 1993 Free Software Foundation, Inc. 


Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this 
permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another: language, under the preceding 
conditions for modified versions, except that this permission notice may be included in translations approved by the Free 
Software F oundation instead of in the original English. 


AUTHORS 
See the GN U CC manual for the contributors to GNU CC. 
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gemtopbm— Convert aGEM IMG file into a portable bitmap 


SYNOPSIS 

gemtopbm [-d] [ gemfile ] 
DESCRIPTION 

Reads aGEM IMG file as input. Reads from stdin if input file is omitted. Produces a portable bitmap as output. 
OPTIONS 

-d Produce output describing the contents of the IM G file. 
BUGS 

D oes not support files containing more than one plane. 
SEE ALSO 

pbmtogem(1), pbm(5) 
AUTHOR 


Copyright© 1988 DiomidisD. Spinellis (dds@cc.ic.ac.uk). 
11 July 1992 
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geqn— Format equations for trotf 


SYNOPSIS 


geqn [ -rvCNR ][-dec ][-Tname ][-Mdir ][-fF ][-sn ][-pn ][-mn ][files ... ] 


DESCRIPTION 


This manual page describes the GN U version of eqn, which is part of the groff document formatting system. eqn compiles 
descriptions of equations enbedded within troff input files into commands that are understood by troff. N ormally, it 
should be invoked using the -e option of groff. T he syntax is quite compatible with UNIX eqn. The output of GNU eqn 
cannot be processed with UN IX trof#; it must be processed with GN U troff. If no files are given on the command line the 
standard input will be read. A filename of - will cause the standard input to be read. 


eqn searches for the file eqnre using the path .:/usr/lib/groff/tmac:/usr/lib/tmac. If it exists, eqn will process it before the 
othe input files. The -r option prevents this. 


GNU eqn does not provide the functionality of neqn: it does not support low-resolution, typewriter-like devices (although it 
may work adequately for very simple input). 


OPTIONS 


-mn 
-Tname 
-Mdir 


-fF 


-sn 


=pn 


USAGE 


Recognize .ca and .en even when followed by a character other than space or newline. 

Don’t allow newlines within delimiters. This option allows eqn to recover better from missing closing 
ddimiters. 

Print the version number. 

Only one gze reduction. 

The minimum point-size isn. eqn will not reduce the size of subscripts or superscripts to asmaller size 
than n. 


The output is for devicename. The only effect of thisisto define a macro name with avalue of 1. Typically, 
eqnrc will use this to provide definitions appropriate for the output device. T he default output device is ps. 


Search dir for eqnrc before the default directories. 

Don't load eqnrc. 

This is equivalent to a gfontF_ command. 

This is equivalent to a gsizen command. T his option is deprecated. eqn will normally set equations at 
whatever the current pointsize is when the equation is encountered. 


This says that subscripts and superscripts should ben points smaller than the surrounding text. T his option 
is deprecated. N ormally, eqn makes sets subscripts and superscripts at 70 percent of the size of the 
surrounding text. 


Only the differences between GNU eqn and UNIX eqn are described here 


M ost of the new features of GN U eqn are based on T eX. There are some references to the differences between T eX and 
GNU eqn as follows; these may safely be ignored if you do not know T eX. 


AUTOMATIC SPACING 
eqn gives each component of an equation a type, and adjusts the spacing between components using that type. Possible types 


are 
ordinary 
operator 
binary 


relation 


An ordinary character such as 1 or x 
A large operator such as ; 

A binary operator such as + 

A relation such as = 


opening An opening bracket such as ( 

closing A closing bracket such as ) 

punctuation A punctuation character such as , 

inner A subformula contained within brackets 

suppress Spacing that suppresses automatic spacing adjustment 


Components of an equation ge@t a type in one of two ways: 


typet e This yidds an equation component that containse but that has typet, wheret is one of the types 
mentioned previously. For example, times is defined as 
type "binary" \(mu 
The name of the type doesn’t have to be quoted, but quoting protects from macro expansion. 
chartypet text | Unquoted groups of characters are split up into individual characters, and the type of each character is 
looked up; this changes the type that is stored for each character; it says that the characters intext from 
now on have typet . For example 
chartype "punctuation" .,;: 
would make the characters .,;: have type punctuation whenever they subsequently appeared in an 
equation. The typet can also be letter or digit; in these cases, chartype changes the font type of the 
characters. See the “Fonts” section, later in this manual page. 


NEW PRIMITIVES 


elsmallovere2 _ Thisissimilar to over; smallover reduces the sizeof e1 and e2; it also puts less vertical space between e1 or 
e2 and the fraction bar. The over primitive corresponds to the \over primitive in display styles; smallover 
corresponds to \over in nondisplay styles. 

vcentere This vertically centerse about the math axis. The math axis is the vertical position about which characters 
such as+ and - are centered; also it is the vertical position used for the bar of fractions. For example, sum is 
defined as 
{type “operator” vcenter size +5 \(*S } 


elaccente2 This sets e2 as an accent over el. e2 iS assumed to be at the correct haght for a lowercase letter; e2 will be 
moved down according if e1 istaller or shorter than a lowercase letter. For example, hat isdefined as 


accent {“"” } 
dotdot, dot, tilde, vec, and dyad are also defined using the accent primitive 
eluaccente2 This sets e2 as an accent under e1. e2 is assumed to be at the correct height for a character without a 


descender; e2 will be moved down if e1 has adescender. utilde is predefined using uaccent asa tilde accent 
bedow the basdine 


splittext This has the same effect as simply text, but text is not subject to macro expansion because it is quoted; 
text will be split up and the spacing between individual characters will be adjusted. 

nosplitt ext This has the same effect as text, but becauset ext isnot quoted it will be subject to macro expansion; t ext 
will not be split up and the spacing between individual characters will not be adjusted. 

eopprime This is a variant of prime that acts as an operator one.It produces a different result from prime in acase 
such aS Aopprimesub1: With opprime the 1 will be tucked under the prime as a subscript to thea (asis 
conventional in mathematical typesetting), whereas with prime the1 will bea subscript to the prime 
character. The precedence of opprime is the same as that of bar and under, which is higher than that of 
everything except accent and uaccent. In unquoted text, a' that is not the first character will be treated 
like opprime. 

specialtexte This constructs a new object frome using agtroff(1) macro named text. When the macro is called, the 
string as will contain the output for e, and the number registers ow, @h, Od, @skern and dskew will contain 
the width, haght, depth, subscript kern, and skew of e. (T he subscript Kern of an object says how much a 
subscript on that object should be tucked in; the kew of an object says how far to the right of the center of 
the object an accent over the object should be placed.) The macro must modify os so that it will output 
the desired result with its origin at thecurrent point, and increase the current horizontal position by the 
width of the object. The number registers must also be modified so that they correspond to the result. 





@O 
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For example, suppose you wanted a construct that cancd’s an expression by drawing a diagonal line through it: 


-EQ 


define cancel ‘special Ca' 


.EN 
-de Ca 


-ds Os \Z'\\*(Os'\v'\\n(@du'\D'1 \\n(@wu -\\n(@hu-\\n(@du'\v'\\n(@hu 


Then you could cancd an expression U with cancel e. 


H ere’s amore complicated construct that draws a box around an expression: 


-EQ 


define box 'special Bx' 


EN 
.de Bx 


-ds Os \Z'\h'1n'\\*(0s'\ 


\Z'\v'\\n(Odu+in'\D'1 \\n(Qwu+2n @'\D'1 @ -\\n(Ohu-\\n(@du-2n'\ 
\D'l -\\n(@wu-2n O'\D'l O \\n(Ohu+\\n(Odut2n"\h'\\n(@wu+2n 


-nr Ow +2n 
-nr Qd +1n 
-nr Oh +1n 


CUSTOMIZATION 


T he appearance of equations is controlled by a large number of parameters. T hese can be set using the set command. 


setpn 


This sets parameter p to valuen; n iS an integer. For example 
set x_height 45 
says that eqn should assume an x height of 0.45 ens. 


Possible parameters are as follows. Values are in units of hundredths of an em unless otherwise stated. T hese descriptions are 
intended to be expository rather than definitive 


minimum_size 


fat_offset 


over_hang 


accent_width 


delimiter_factor 


delimiter_shortfall 


null_delimiter_space 
script_space 
thin_space 
medium_space 


thick_space 


eqn will not set anything at a smaller point size than this. The value is in points. 
The fat primitive enboldens an equation by overprinting two copies of the equation horizontally 
offset by this amount. 


A fraction bar will be longer by twice this amount than the maximum of the widths of the 
numerator and denominator; in other words, it will overhang the numerator and denominator by 
at least this amount. 


W hen bar or under is applied to a single character, the line will be this long. N ormally, bar or 
under produces a line whose length is the width of the object to which it applies; in the case of a 
single character, this tends to produce a line that looks too long. 


Extensible delimiters produced with the left and right primitives will have a combined height and 
depth of at least this many thousandths of twice the maximum amount by which the subequation 
that the delimiters enclose extends away from the axis. 


Extensible delimiters produced with the left and right primitives will have a combined height and 
depth not less than the difference of twice the maximum amount by which the subequation that 
the ddimiters enclose extends away from the axis and this amount. 


This much horizontal space is inserted on each side of a fraction. 

The width of subscripts and superscripts is increased by this amount. 

This amount of space is automatically inserted afte: punctuation characters. 
This amount of space is automatically inserted on either side of binary operators. 
This amount of space is automatically inserted on either side of relations. 


x_height The height of lowercase letters without ascenders such as x. 


axis_height The height above the baseline of the center of characters such as + and -. It isimportant that this 
value be correct for the font you are using. 

default_rule thickness This should set to the thickness of the \(ru character, or the thickness of horizontal lines produced 
with the\D escape sequence. 











num4 The over command will shift up the numerator by at least this amount. 

num2 The smallover command will shift up the numerator by at least this amount. 

denom1 The over command will shift down the denominator by at least this amount. 

denom2 The smallover command will shift down the denominator by at least this amount. 

sup1 Normally superscripts will be shifted up by at least this amount. 

sup2 Superscripts within superscripts or upper limits or numerators of smallover fractions will be shifted 
up by at least this amount. T his is usually less than sup1. 

sup3 Superscripts within denominators or square roots or subscripts or lower limits will be shifted up by 
at least this amount. This is usually less than sup2. 

sub1 Subscripts will normally be shifted down by at least this amount. 

sub2 W hen there is both a subscript and a superscript, the subscript will be shifted down by at least this 
amount. 

sup_drop T he baseline of a superscript will be no more than this anount below the top of the object on 
which the superscript is set. 

sub_drop The baseline of a subscript will be at least this much below the bottom of the object on which the 
subscript is set. 

big op spacing! The baseline of an upper limit will be at least this much above the top of the object on which the 
imit is set. 

big_op_spacing2 The baseline of a lower limit will be at least this much below the bottom of the object on which the 
imit is set. 

big_op_spacing3 The bottom of an upper limit will be at least this much above the top of the object on which the 
imit is set. 

big_op_spacing4 The top of alower limit will be at least this much bdow the bottom of the object on which the 
imit is set. 

big_op_spacing5S This much vertical space will be added above and beow limits. 

baseline_sep T he baselines of therowsin a pile or matrix will normally be this far apart. In most cases, this 
should be equal to the sum of num1 and denomt. 

shift_down The midpoint between the top baseline and the bottom baseline in a matrix or pile will be shifted 
down by this much from the axis. In most cases, this should be equal to axis_height. 

column_sep This much space will be added between columnsin a matrix. 

matrix_side_sep This much space will be added at each side of a matrix. 

draw_lines If this is nonzero, lines will be drawn using the \p escape sequence rather than with the \1 escape 
sequence and the \ (ru character. 

body_height The amount by which the height of the equation exceeds this will be added as extra space before 
the line containing the equation (using \x.) The default value is 85. 

body_depth The amount by which the depth of the equation exceeds this will be added as extra space after the 
line containing the equation (using \x.) The default value is 35. 

nrotf If thisis nonzero, then ndefine will behave like define and tdefine will be ignored; otherwise, 


tdefine will behave like define and ndefine will be ignored. T he default value is oa. (T hisis typically 
changed to 1 by the eqnrc file for the ascii and latin1 devices.) 


A more precise description of the role of many of these parameters can be found in Appendix H of TheT eXbook. 
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MACROS 


M acroscan take arguments. In amacro body, $ » wheren is betwen 1 and 9, will be replaced by thenth argument if the 
macro is called with arguments, if there are faver thann arguments, it will be replaced by nothing. A word containing a left 
parenthesis where the part of the word before the left parenthesis has been defined using thedefine command will be 
recognized as a macro call with arguments; characters following the left parenthesis up to a matching right parenthesis will be 
treated as comma-separated arguments; commas inside nested parentheses do not terminate an argument. 


sdefinenameXanythingX  Thisislikethe define command, but name will not be recognized if called with arguments. 
includefi le Include the contents of file. Linesof file beginning with .ca or .en will be ignored. 


ifdefname Xanyt hi ngX If name has been defined by define (or has been automatically defined because name isthe output 
device), process anyt hing; otherwise ignore anything. 


x can be any character not appearing in anything. 


FONTS 


eqn normally uses at least two fonts to set an equation: an italic font for letters, and aRoman font for everything else The 
existing gfont command changes the font that is used as the italic font. By default this is 1. The font that is used as the 
Roman font can be changed by using the new grfont command. 


grfontf Set the Roman font tot. 


The italic primitive uses the current italic font set by gfont; the Roman primitive uses the current Roman font set by grfont. 
There is also anew gbfont command, which changes the font used by the bold primitive If you only use the Roman, italic, 
and bold primitives to change fonts within an equation, you can change all the fonts used by your equations just by using 
gfont, grfont, and gbfont commands. 


You can control which characters are treated as letters (and therefore set in italic) by using thechartype command described 
earlier. A type of letter will cause a character to be set in italic type. A type of digit will cause a character to be set in Roman 


type. 
FILES 


/usr/lib/groff/tmac/eqnrc _ Initialization file 


BUGS 


Inline equations will be set at the pointsize that is current at the beginning of theinput line. 


SEE ALSO 
groff(1), gtroft(1), groff_font(5), The T eXbook 


getlist 
getlist— Get alist from an NNTP server 


SYNOPSIS 


getlist [ -h host ][list [ pattern [ types ]]] 


DESCRIPTION 
The getlist program obtains alist from an NN TP server and sends it to standard output. 


The list may be one of active, active.times, distributions, Of newsgroups. T hese values request the active(5), 
active.times, /news/lib/distributions, OF /news/1lib/newsgroups files, respectively. 


If the -h flag is used, then the program connects to the server on the specified host. T he default is to connect to the server 
specified in the inn.cont(5) file 
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If thelist parameter is active, then the pattern and types parameters may be used to limit the output. When pattern is 
used, only active lines with groups that match according to wildmat(3) are printed. When types is also given, only active lines 
that havea fourth field starting with a character found intypes are printed. 


For example, the following command will obtain the one-line descriptions of all newsgroups found on uuNeET: 
getlist -h news.uu.net newsgroups 

The following line lists all groups where local postings are permitted, moderated, or aliased: 

getlist active '*' ym= 


N ote that the listing files other than the active file isa common extension to the NNTP protocol and may not be available 
on all servers. 


HISTORY 


Written by Landon Curt N oll (<chongo@toad. com>) for InterN e&tN ews. 


SEE ALSO 


active(5), nnrpd(8), wildmat(3) 


getopt 


getopt— Parse command options 


SYNOPSIS 


set - 'getopt optstring $*' 


DESCRIPTION 


getopt iS used to break up optionsin command lines for easy parsing by shell procedures, and to check for legal options. 
optstring iS a string of recognized option letters; see getopt(3). If a letter is followed by a colon, the option is expected to 
have an argument that may or may not be separated from it by whitespace The special option — - is used to delimit the end 
of the options. getopt will place — - in the arguments at the end of the options, or recognize it if used explicitly. The shell 
arguments ($1 $2 ...) are reset so that each option is preceded by a- and inits own shal argument; each option argument 
is also in its own shell argument. 


EXAM PLE 


The following code fragment shows how one might process the arguments for a command that can take the optionsa and b, 
and the option o, which requires an argument: 


set — 'getopt abo: $*' 
if test $7 != 0 
then 
echo ‘Usage: ... 
exit 2 
fi 
fori 
do 
case "$i" 
in 
-a,-b) 
flag=$i; shift;; 
-0) 
oarg=$2; shift; shift;; 
--) 
shift; break;; 
esac 


done 
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This code will accept any of the following as equivalent: 


cmd -aoarg file file 

cmd -a -o arg file file 
cmd -oarg -a file file 
cmd -a -oarg -- file file 


SEE ALSO 
sh(1), getopt(3) 


DIAGNOSTICS 


getopt prints an error message on the standard error output when it encounters an option letter not included in optstring. 


HISTORY 


Written by H enry Spence, working from a Bell Labs manual page. Behavior bdieved identical to the Bell version. 


BUGS 
W hatever getopt(3) has. 


Arguments containing whitespace or enbedded shell meta characters generally will not survive intact; this looks easy to fix 
but isn’t. 

Theerror message for an invalid option is identified as coming from getopt rather than from the shell procedure containing 
the invocation of getopt; this, again, is hard to fix. 


The precise best way to use the set command to set the arguments without disrupting the value(s) of shell options varies 
from oneshel version to another. 


21 June1993 

giftopnm 

giftopnm— Convert aGIF file into a portable anymap 
SYNOPSIS 

giftopnm [-verbose][-comments][-image N][GIFfile] 
DESCRIPTION 

Reads a GIF file for input, and outputs portable anymap. 
OPTIONS 

-verbose Produces verbose output about the GIF file input. 

-comments Only outputs GIF89 comment fields. 

- image Outputs the specified GIF image from the input GIF archive (wheren is1, 2, 20...). Normally, thereis 


only one image per file, so this option is not needed. 
All flags can be abbreviated to their shortest unique prefix. 
BUGS 


This does not correctly handle the Plain T ext Extension of the GIF 89 standard, since! did not have any example input files 
containing then. 


gindxbib 


SEE ALSO 


ppmtogif(1), ppm(5) 


AUTHOR 
Copyright © 1993 by D avid K oblas (koblas@netcom. com) 


29 September 1993 


gindxbib 


gindxbib— M ake inverted index for bibliographic databases 


SYNOPSIS 
gindxbib [-vw] [-c file] [-d dir] [-f file] [-h n] [-i string] 
[-k n] [-l n] [-n n] [-o file] [-t n] [filename ...] 
DESCRIPTION 


gindxbib makes an inverted index for the bibliographic databases in filename... for use with grefer(1), glookbib(1), and 
1kbib(1). The index will be named fi | ename .i; the index is written to a temporary file which isthen renamed to this. If no 
filenames are given on the command line because the -# option has been used, and no -o option is given, the index will be 
named Ind.i. 


Bibliographic databases are divided into records by blank lines. Within a record, each fields starts with as character at the 
beginning of aline Fields havea oneletter name that follows thes character. 


The values set by the -c, -n, -1, and -t options are stored in the index; when the index is searched, keys will be discarded and 
truncated in amanner appropriate to these options, the original keys will be used for verifying that any record found using 
the index actually contains the keys. T his means that a user of an index need not know whether these options were used in 
the creation of the index, provided that not all the keys to be searched for would have been discarded during indexing and 
that the user supplies at least the part of each key that would have remained after being truncated during indexing. The value 
set by the -i option is also stored in the index and will be used in verifying records found using the index. 


OPTIONS 

-v Print the version number. 

-w Index whole files. Each fileis a separate record. 

-cfile Read the list of common words from file instead of /usr/1lib/groff/eign. 

-ddir Usedir asthe pathname of the current working directory to store in theindex, instead of the path printed 
by pwa(1). Usually dir will bea symbolic link that points to the directory printed by pwa(1). 

-ffile Read the files to be indexed from file. If fileis -, files will be read from the standard input. The -f option 
can be given at most once. 

-istring Don’t index the contents of fidds whose names are in string. Initially, string is xyz. 

-hn Use the first prime greater than or equal ton for the size of the hash table Larger values of n will usually 
make searching faster, but will make the index larger and gindxbib use more memory. Initially, n is 997. 

-kn Use at most n keys per input record. Initially, n is 100. 

-In Discard keys that are shorter than n. Initially, n is 3. 

=mn Discard then most common words. Initially, n is 100. 

-obasename Theindex should be named basename .i. 


-tn Truncate keys to n. Initially, n is. 
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FILES 
filename .i Index 
Ind.i D efault index name 
/usr/lib/groff/eign List of common words 
indxbibXXXXXX Temporary file 

SEE ALSO 


grefer(1), 1kbib(1), glookbib(1) 
Groff Vergon 1.09, 16 April 1993 


glookbib 


glookbib— Search bibliographic databases 


SYNOPSIS 


glookbib [ -v ][-istring ][-tn ] filename ... 


DESCRIPTION 


glookbib prints a prompt on the standard error (unless the standard input is not a terminal), reads from the standard input a 
line containing a set of keywords, searches the bibliographic databasesti!ename ... for references containing those keywords, 
prints any references found on the standard output, and repeats this process until the end of input. For each database 
filename to be searched, if an index filename .i created by gindxbib(1) exists, then it will be searched instead; each index can 
cover multiple databases. 


OPTIONS 
-v Print the version number. 
-istring W hen searching files for which no index exists, ignore the contents of fields whose names arein string. 
-tn Only require the first n characters of keys to be given. Initially, n ise. 
FILE 
filename .i Index files 
SEE ALSO 


grefer(1), 1kbib(1), gindxbib(1) 


gnroft 


gnroff— Emulate nroff command with grotf 


SYNOPSIS 


gnroff [ -h ][-i ][-mname ][-nnum ][-olist ][-rcn ][-Tname ][file...] 


DESCRIPTION 
The gnroff script enulates the nroff command using groff. The -T option with an argument other than ascii and latin1 
will be ignored. The -h option is equivalent to the grotty -h option. The -i, -n, -m, -o, and -r options have the effect 
described in gtrof#(1). In addition, gnroff silently ignores options of -e, -q, or -s. 


“o 


Groff Vergon 1.09, 17 May 1993 


SEE ALSO 


groff(1), gtroft(1), grotty(1) 


gouldtoppm 


gouldtoppm— C onvert Gould scanner file into a portable pixmap 


SYNOPSIS 


gouldtoppm[goul dfile] 


DESCRIPTION 


Reads a file produced by theG ould scanner as input. Produces a portable pixmap as output. 


SEE ALSO 
ppm(5) 


AUTHOR 
Copyright© 1990 by Stephen Paul Lesniawski 


20 May 1990 


Qp1c 
gpic— Compile pictures for troff or T eX 


SYNOPSIS 


gpic [ -nvC ][filename ... ] gpic -t [ -cvzC ][filename ... ] 


DESCRIPTION 


This manual page describes the GN U version of pic, which is part of the groff document formatting system. pic compiles 
descriptions of pictures enbedded within troff or T eX input files into commands that are understood by TeX or troff. 
Each picture starts with a line beginning with .ps and ends with aline beginning with .pe. Anything outside of .ps and .PE 
is passed through without change. 


It isthe user’s responsibility to provide appropriate definitions of thers and pe macros. W hen the macro package being used 


does not supply such definitions (for example, old versions of -ms), appropriate definitions can be obtained with -mpic: T hese 
will center each picture. 


OPTIONS 


O ptions that do not take arguments may be grouped behind a single -. T he special option -- can be used to mark the end of 
the options. A filename of - refers to the standard input. 


-C Recognize .ps and .PE even when followed by a character other than space or newline. 

-n Don’t use the groff extensions to the troff drawing commands. You should use this if you are using a 
postprocessor that doesn’t support these extensions. T he extensions are described in groff_out(5). The-n option 
also causes pic not to use zero-length lines to draw dots in troff mode 

-t TeX mode 

-¢ Be more compatible with tpic. Implies -t. Lines beginning with n are not passed through transparently. Lines 
beginning with . are passed through with the initial . changed to \. A line beginning with .ps is given special 
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treatment: It takes an optional integer argument specifying the line thickness (pen size) in milli-inches; a missing 
argument restores the previous line thickness; the default line thickness is 8 milli-inches. T he line thickness thus 
specified takes effect only when a nonnegative line thickness has not been specified by use of the thickness 
attribute or by setting the 1inethick variable 


-V Print the version number. 
-2 In T eX mode draw dots using zero-length lines. 


The following options supported by other versions of pic are ignored: 


-D D raw all lines using the \p escape sequence. pic always does this. 
-Tdev Generate output for the troff devicedev. This is unnecessary because the troff output generated by pic isdevice 
independent. 
USAGE 


This section describes only the differences between GNU pic and the original version of pic. M any of these differences also 
apply to newer versions of UNIX pic. 
mode 


mode is fabled by the -t option. In mode, pic will define a vbox called ngraph for each picture. You must yourself print that 
vbox using, for example, the command: 


\centerline{\box\graph} 


Actually, since the vbox has ahaight of zero, this will produce slightly more vertical space above the picture than below it, the 
line 

\centerline{\raise 1em\box\graph} 

would avoid this. 

You must use a driver that supports the tpic specials, version 2. 


Lines beginning with \are passed through transparently; a% is added to the end of the line to avoid unwanted spaces. You 
can safely use this feature to change fonts or to change the value of \baselineskip. Anything ase may wal produce undesir- 
able results; use at your own risk. Lines beginning with a period are not given any special treatment. 


COMMANDS 

for variable = exprl to expr2 W hile the value of vari able iSless than or equal to expr2, do body and increnent 

by [*]expr3] do X body X variable by expr3; if by isnot given, increment vari able by 1. If expr3 is prefixed 

[Set variable to exprl by * then variable will instead be multiplied by expr3.x can be any character not 
occurring in body. 

if expr then X if-true X Evaluate expr; if itisnonzero,doit-true; otherwise doit-false.u can beany 

[else Y if-false Y] character not occurring inif-true.¥ can be any character not occurring inif-false. 

print arg ... Concatenate the arguments and print as aline on stderr. Each arg must be an 
expression, a position, or text. Thisis useful for debugging. 

command arg ... Concatenate the arguments and pass them through asalineto troff or TeX. Each 
arg must be an expression, a position, or text. T hishas a similar effect to aline 
beginning with . or \, but allows the values of variables to be passed through. 

sh X command X Passcommand to ashal. x can beany character not occurring in command. 

copy "filename" Includetilename at thispoint in the file 

copy ["filename"] thru X body X This construct does body once for each line of filename; thelineis split into blank- 

[until "word"] ddimited words, and occurrences of $ iin body, fori between 1 and 9, are replaced 

copy ["filename"] thru macro by thei -th word of theline If fil ename is not given, lines are taken from the current 

[until "“word"] input up to .Pe. If an unti1 clause is specified, lines will be read only until aline the 


first word of which is wor d; that line will then be discarded. x can be any character 
not occurring in body. For example 


“= 


PS 
copy thru % circle at ($1,$2) % until "END" 
12 
34 
5 6 
END 
box 
.PE 


is equivalent to 
.PS 
circle at (1,2) 
circle at (3,4) 
circle at (5,6) 
box 
.PE 


The commands to be performed for each line can also be taken from a macro 
defined earlier by giving the name of the macro as the argument to thru. 


reset variablel, variable2... Reset predefined variablesvariable1, variable2 ... to thar default values. If no 
arguments are given, reset all predefined variables to ther default values. N ote that 
assigning a value to scale also causes all predefined variables that control dimensions 
to be reset to thar default values times the new value of scale. 


plot expr ["text"] Thisis a text object which is constructed by using asa format string for text sprintf 
with an argument of expr. Iftext isomitted, a format string of %g is used. Attributes 
can be specified in the same way as for a normal text object. Be very careful that you 
specify an appropriate format string; pic does only very limited checking of the 
string. This is deprecated in favor of sprintf. 


variable :=expr This is similar to = except vari abl e must already be defined, and the value of 
variable will be changed only in theinnermost block in which it is defined. (By 
contrast, = defines the variable in the current block if it is not already defined there, 
and then changes the value in the current block.) 


Arguments of the form 
XanythingX 


are also allowed to be of the form: 
anything 


In this case, anything can contain balanced occurrences of and .BR. Strings may contain x or imbalanced occurrences of 
and .BR. 


EXPRESSIONS 
T he syntax for expressions has been significantly extended: 


x"y (exponentiation) 

sin(x) 

cos (x) 

atan2(y ,x) 

log(x) (base 10) 

exp(x) (base 10, ie 10'-.4m'x'.4m') 

sqrt (x ) 

int (x) 

rand() (return a random number between @ and 1) 
rand(x) (return a random number between 1 and x; deprecated) 
max (el ,e2) 

min(el ,e2) 

te 
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e2 
e2 
e2 
el e2 
el e2 
e1 > e2 
e1 <= e2 
e1 < e2 
“stri"=="str2" 
“stri"!="str2" 


e1 
e1 
e1 


ll -- ge 
tow Wt -- ge 


vo 


String comparison expressions must be parenthesized in some contexts to avoid ambiguity. 


OTHER CHANGES 


A bare expression, expr, is acceptable as an attribute it is equivalent to dir expr, where dir is the current direction. For 
example 


line 2i 





means draw aline2 incheslong in the current direction. 


The maximum width and haght of the picture are taken from the variables maxpswid and maxpsht. Initially, these have values 
8.5 and 11. 


Scientific notation is allowed for numbers. For example 

xX = 5e-2 

Text attributes can be compounded. For example 

"foo" above ljust 

is legal. 

Thereisno limit to the depth to which blocks can be examined. For example 


[A: [B: [C: box ]]] with .A.B.C.sw at 1,2 
circle at last [].A.B.C 


is acceptable. 
Arcs now have compass points determined by the circle of which the arc isa part. 
Circles and arcs can be dotted or dashed. In mode, splines can be dotted or dashed. 


Boxes can have rounded corners. T he rad attribute specifies the radius of the quarter-circles at each corner. If no rad or diam 
attribute is given, a radius of boxrad is used. Initially, boxrad has a value of @. A box with rounded corners can be dotted or 
dashed. 


The .ps line can have a second argument specifying a maximum height for the picture. If the width of zero is specified, the 
width will be ignored in computing the scaling factor for the picture. N ote that GN U pic will always scale a picture by the 
same amount vertically as horizontally. T his is different from the D WB 2.0 pic, which may scale a picture by a different 
amount vertically than horizontally if a height is specified. 

Each text object has an invisible box associated with it. The compass points of a text object are determined by this box. The 
implicit motion associated with the object is also determined by this box. The dimensions of this box are taken from the 
width and height attributes; if the width attribute is not supplied, then the width will be taken to be textwia; if thehaght 
attribute is not supplied, then the height will be taken to bethe number of text strings associated with the object times 
textht. Initially textwid and textht havea value of 0. 

In places where a quoted text string can be used, an expression of theform: 


sprintf (format ,arg,...) 


“oF 


can also be used; this will produce the arguments formatted according to format , which should be a string as described in 
printf(3), appropriate for the number of arguments supplied, using only thee, f, g, or format characters. 


The thickness of the lines used to draw objects is controlled by the 1inethick variable. T his gives the thickness of lines in 
points. A negative value means use the default thickness: in output mode, this means use a thickness of 8 milli-inches; in 
output mode with the -c option, this means use the line thickness specified by .ps lines; in trot output mode, this means 
use a thickness proportional to the point size. A zero value means draw the thinnest possible line supported by the output 
device Initially, it has a value of -1. Thereis also a thick[ness] attribute. For example, 


circle thickness 1.5 


would draw a circle using aline with a thickness of 1.5 points. The thickness of lines is not affected by the value of the scale 
variable, nor by the width or height given in the .ps line. 


Boxes (including boxes with rounded corners), circles, and ellipses can be filled by giving then an attribute of filled}. This 
takes an optional argument of an expression with a value between @ and 1; 0 will fill it with white 1 with black, values in 
between with a proportionally gray shade. A value greater than 1 can also be used: this meansfill with the shade of gray that 
is currently being used for text and lines. N ormally this will be black, but output devices may providea mechanism for 
changing this. W ithout an argument, then the value of the variable fi11vai will be used. Initially, thishasa valueof @.5. The 
invisible attribute does not affect the filling of objects. Any text associated with a filled object will be added after the object 
has been filled, so that the text will not be obscured by the filling. 


Arrowheads will be drawn as solid triangles if the variable arrowhead isnonzero and either mode is enabled or the -x option 
has been given. Initially, arrowhead has a value of 1. 

The troff output of pic is device independent. The -T option is therefore redundant. All numbers are taken to bein inches; 
numbers are never interpreted to bein troff machine units. 


O bjects can have an aligned attribute. This will only work when the postprocessor is grops. Any text associated with an 
object having the aligned attribute will be rotated about the center of the object so that it is aligned in the direction from the 
start point to the end point of the object. N ote that this attribute will have no effect for objects whose start and end points 
are coincident. 


In places where nth isallowed, expr ‘th is also allowed. N ote that ‘th isa single token: no space is alowed between the ' and 
the th. For example, 


fori =1 to 4 do{ 
line from 'i'th box.nw to ‘i+1'th box.se 
} 


/usr/lib/groff/tmac/tmac.pic Sampledefinitions of the PS and PE macros. 


SEE ALSO 


gtroff(1), groff_out(5), tex(1) 


TPIC: PIC for AT&T Bal Laboratories, Computing Science T echnical Report N 0. 116, PIC— A Graphics Language for 
T ypesetting. (T his can be obtained by sending an email message to netlib@research.att.com with a body of “send 116 from 
research/cstr.”) 


BUGS 


Input characters that are illegal for grot# (those with ASCII code 0 or between 013 and 037 octal or between 0200 and 0237 
octal) arerejected even in mode. 


The interpretation of fi11val isincompatible with the pic in 10th edition UNIX, which interprets @ as black and 1 as white. 


Part |: User Commands 
gprof 


gprof— D isplay call graph profile data 
SYNOPSIS 


gprof [ -abcsz ] [ -ej-E name ] [-fj-F name ][-k fromname toname ] [ objfile [ gmon.out ]] 


DESCRIPTION 
gprof produces an execution profile of C, Pascal, or Fortran77 programs. The effect of called routinesis incorporated in the 
profile of each caller. The profile data istaken from the call graph profile file (gmon. out default), which is created by programs 
that are compiled with the -pg option of cc(1), pc(1),and #77(1). T he -pg option also links in versions of the library routines 
that are compiled for profiling. gprof reads the given object file (the default is a. out) and establishes the rdation between its 
symbol table and the call graph profile from gmon.out. If more than one profile file is specified, the gprof output shows the 
sum of the profile information in the given profile files. 
gprof Calculates the amount of time spent in each routine. N ext, these times are propagated along the edges of the call graph. 
Cycles are discovered, and calls into a cycle are made to share the time of the cycle. The first listing shows thefunctions 
sorted according to the time they represent, including the time of their call graph descendants. Bdow each function entry is 
shown its (direct) call graph children, and how thar times are propagated to this function. A similar display above the 
function shows how this function’s time and the time of its descendants is propagated to its (direct) call graph parents. 


Cycles are also shown, with an entry for the cycle as a whole and a listing of the manbers of the cycle and their contributions 
to the time and call counts of the cycle. 

Second, a flat profile is given, similar to that provided by prof(1). This listing gives the total execution times, the call counts, 
thetimein milliseconds, the call spent in the routineitself, and the timein milliseconds the call spent in the routine itself, 
including its descendants. 


Finally, an index of the function names is provided. 





OPTIONS 

The following options are available: 

-a Suppresses the printing of statically declared functions. If this option is given, all relevant information 
about the static function (for example, time samples, calls to other functions, calls from other 
functions) bdongs to the function loaded just before the static function in the objfile file 

-b Suppresses the printing of a description of each field in the profile 

-¢ The static call graph of the program is discovered by a heuristic that examines the text space of the 
object file Static-only parents or children are shown with call counts of 0. 

-e name Suppresses the printing of the graph profile entry for routinename and all its descendants (unless they 
have other ancestors that aren't suppressed). M ore than one -e option may be given. O nly one name 
may be given with each -e option. 

-E name Suppresses the printing of the graph profile entry for routinename (and its descendants) as -e, 








previously and also excludes the time spent in name (and its descendants) from the total and percentage 
time computations. (For example, -£ mcount -E mcleanup is the default.) 


-f name Prints the graph profile entry of only the specified routinename and its descendants. M ore than one -t 
option may be given. Only onename may begiven with each -f option. 
-F name Prints the graph profile entry of only the routine name and its descendants (as -f, previously) and also 


uses only the times of the printed routines in total time and percentage computations. M ore than one 
-F option may be given. Only onename may be given with each -F option. T he -F option overrides the 
-E option. 

-k fromname toname Will delete any arcsfrom routinet romname to routinet oname. Thiscan be used to break undesired 
cycles. M ore than one -k option may be given. O nly one pair of routine names may be given with each 
-k option. 
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-s A profile file gmon.sum is produced that represents the sum of the profile information in all the specified 
profile files. This summary profile file may be given to later executions of gprof (probably also with an 
-s) to accumulate profile data across several runs of an objfile file 


“V Prints the version number for gprof, and then exits. 
-Z Displays routines that have zero usage (as shown by call counts and accumulated time). T hisis useful 
with the -c option for discovering which routines were never called. 
FILES 
a.out Thename list and text space 
gmon. out D ynamic call graph and profile 
gmon. sum Summarized dynamic call graph and profile 
SEE ALSO 


monitor(3), profil(2), cc(1), prof(1) 


“An Execution Profiler for M odular Programs,” by S. Graham, P. Kessler, M. McK usick; Software— Practice and Experience, 
Vol. 13, pp. 671-685, 1983. 


“gprot: A Call Graph Execution Profiler,” by S. Graham, P. Kessler, M. M cK usick; Proceedings of theSIGPLAN '82 
Symposium on Compiler Condruction, SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, J une 1982. 


HISTORY 
gprof appeared in 4.2 BSD. 


BUGS 


The granularity of the sampling is shown, but remains statistical at best. W e assume that the time for each execution of a 

function can be expressed by the total time for the function divided by the number of times the function is called. T hus, the 
time propagated along the call graph arcsto the function's parents is directly proportional to the number of times that arc is 
traversed. 


Parents that are not thansdves profiled will have the time of their profiled children propagated to them, but they will appear 
to be spontaneously invoked in the call graph listing, and will not have thar time propagated further. Similarly, signal 
catchers, even though profiled, will appear to be spontaneous (although for more obscure reasons). Any profiled children of 
signal catchers should have ther times propagated properly, unless the signal catcher was invoked during the execution of the 
profiling routine, in which case all is lost. 





The profiled program must call exit(2) or return normally for the profiling information to be saved in the gmon. out file. 
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grefer— Preprocess bibliographic references for groff 
SYNOPSIS 
grefer [-benvCPRS] [-a n] [-c fields] [-f n] [-i fields] [-k field] [-1 m,n] [-p filename] [-s fields] [-t n] [-B 
field.macro] [filename...] 
DESCRIPTION 


This file documents the GN U version of refer, which is part of the grotf document formatting system. refer copies the 
contents of filename... to thestandard output, except that lines between .{ and .] are interpreted as citations, and lines 
between .r1 and .r2 areinterpreted as commands about how citations are to be processed. 
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Each citation specifies a reference. The citation can specify a reference that is contained in a bibliographic database by giving 
a set of keywords that only that reference contains. Alternatively, it can specify a reference by supplying a database record in 
the citation. A combination of these alternatives is also possible. 


For each citation, refer can produce a mark in the text. This mark consists of some label that can be separated from the text 
and from other labds in various ways. For each reference, it also outputs groff commands that can be used by a macro 
package to produce a formatted reference for each citation. The output of refer must therefore be processed using a suitable 
macro package. The -ms and -me macros are both suitable. The commands to format a citation’s reference can be output 
immediately after the citation, or the references may be accumulated, and the commands output at some later point. If the 
references are accumulated, then multiple citations of the same reference will produce a single formatted reference 


The interpretation of lines between .r1 and .R2 as commands isa new feature of GNU refer. Documents making use of this 
feature can still be processed by UNIX refer just by adding the lines: 


-de R1 
.ig R2 


to the beginning of the document. This will cause troff to ignore everything between .r1 and .r2. The effect of some 
commands can also be achieved by options. T hese options are supported mainly for compatibility with UNIX refer. It is 
usually more convenient to use commands. 


refer generates .1F lines so that filenames and line numbers in messages produced by commands that read refer output will 
be correct; it also interprets lines beginning with .1F so that filenames and line numbers in the messages and .1¢ lines that it 
produces will be accurate even if the input has been preprocessed by acommand such as gsoelin(1). 








OPTIONS 
M ost options are equivalent to commands (for a description of these commands, see “C ommands,” later in this manual 
page): 
-b no-label-in-text; no-label-in-reference 
-e accumulate 
-n no-default -database 
-C compatible 
-P move -punctuation 
-S abel "(A.niQ) ', ' (D.y{D)"; bracket-label "(") "; " 
-an reverse An 
-cfields capitalize fields 
-fn abel %n 
-ifields search-ignore fiel ds 
-k abel L%a 
-kfield abel field%a 
- abel A.nD.y%a 
-1m abel A.n+mD.y%a 
-1,n abel A.nD.y-n%a 
-1m,n abel A.n+mD.y-n%a 
-pfil ename database filename 
-ss pec sort spec 
-tn search-truncate n 





T hese options are equivalent to the following commands with the addition that the filenames specified on the command line 
are processed as if they were arguments to the bibliography command instead of in the normal way: 


-B Annotate X AP; no-label-in-reference 


-Bfield.macro Annotate field macro; no-label-in-reference 


The following options have no equivalent commands: 


-v Print the version number 
-R Don’t recognize lines beginning with .r1/.R2 
USAGE 


BIBLIO GRAPHIC DATABASES 


The bibliographic database is a text file consisting of records separated by one or more blank lines. Within each record, fields 
start with a% at the beginning of aline Each field has a one-character name that immediatey follows thes. It is best to use 
only uppercase and lowercase letters for the names of fidds. The name of the field should be followed by exactly one space, 
and then by the contents of the fidd. Empty fields are ignored. The conventional meaning of each field is as follows: 


A Thename of an author. If the name containsa title such as] r. at the end, it should be separated from the 
last name by a comma. There can be multiple occurrences of thea field. The order is significant. It isa 
good idea always to supply an a field or aa fidd. 


B For an article that is part of abook, the title of the book. 
C The place (city) of publication. 
D The date of publication. The year should be specified in full. If the month is specified, the name rather 


than thenumber of the month should be used, but only the first three letters are required. It isa good idea 
always to supply ap field; if the date is unknown, a value such as in press OF unknown can be used. 


E For an article that is part of abook, the name of an editor of the book. W here the work has editors and no 
authors, the names of the editors should be given asa fields (ed) or (eds) should be appended to the last 
author. 

G U.S. government ordering number. 

I The publisher (issuer). 

J For an article in a journal, the name of the journal. 

K K eywords to be used for searching. 

L Label. 

N Journal issue numbe.. 

0 O ther information. T his is usually printed at the end of the reference 

P Page number. A range of pages can be specified as m-n. 

Q The name of the author, if the author is not a person. This will only be used if there are noa fields. There 


can only be onea field. 

Technica report number. 

Series name. 

Title. For an article in a book or journal, this should be the title of the article. 
Volume number of the journal or book. 

Annotation. 


< < AH wn BD 


For all fidds except a and e, if there is more than one occurrence of a particular fidd in a record, only the last such field will 
be used. 


If accent strings are used, they should follow the character to be accented. T his means that the am macro must be used with 
the -ms macros. Accent strings should not be quoted: use one \ rather than two. 


CITATIONS 
The format of a citation is 


-[opening-text 
flags keywords 
fields 


-]closing-text 
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Theopening-text,closing-text, andflags Components are optional. Only oneof thekeywords and fields Components need 
be specified. 


Thekeywords Component says to search the bibliographic databases for a reference that contains all the words in keywords. It 
isan error if more than one reference if found. 


Thefields components specifies additional fields to reolace or supplement those specified in the reference When references 
are being accumulated and thekeywords component is nonempty, then additional fields should be specified only on the first 
occasion that a particular reference is cited, and will apply to all citations of that reference 


The@opening-text andclosing-text Component specifies strings to be used to bracket the label instead of the strings specified 
in the bracket-1abel command. If either of these components is nonempty, the strings specified in the bracket- label 
command will not be used; this behavior can be altered using the | and ] flags. N ote that leading and trailing spaces are 
significant for these components. 





Theflags component isa list of nonalphanumeric characters, each of which modifies the treatment of this particular 
citation. UNIX refer will treat these flags as part of the keywords and so will ignore them because they are 
nonalphanumaic. T he following flags are currently recognized: 


# This says to use the labd specified by the short-1abe1 command, instead of that specified by the 1abe1 command. 
If no short label has been specified, the normal label will be used. T ypically, the short label is used with author- 
date labels and consists of only the date and possibly a disambiguating letter; the # is supposed to be suggestive of 
anumaic type of labd. 

[ Precede opening-text with thefirst string specified in the bracket -1abel Command. 

] Follow cl osing-text with thesecond string specified in the bracket -1abel command. 


O ne advantage of using the | and | flags rather than including the brackets in opening-text andclosing-text isthat you can 
change the style of bracket used in the document just by changing the bracket -1labe1 command. Another advantage is that 
sorting and merging of citations will not necessarily be inhibited if the flags are used. 


If alabel isto beinserted into the text, it will be attached to the line preceding the .; line If thereisno such line then an 
extra line will be inserted before the .{ line and a warning will be given. 


There isno special notation for making a citation to multiple references. J ust use a sequence of citations, one for each 
reference. Don’t put anything between the citations. The labs for all the citations will be attached to the line preceding the 
first citation. T he label's may also be sorted or merged. (See the description of the <> label expression, and of the sort- 
adjacent- labels and abbreviate-label-ranges command.) A labd will not be merged if its citation has a nonempty openi ng- 
text OFclosing-text. However, the labds for a citation using the} flag and without any c! osing-text immediately followed 
by acitation using the; flag and without any opening-text may be sorted and merged even though the first citation’s 
opening-text or the second citation’sc! osing-text isnonempty. (If you want to prevent this, just make the first citation’s 
closing-text \&) 


COMMANDS 


Commands ae contained between lines starting with .r1 and .r2. Recognition of these lines can be prevented by the-r 
option. When an .ri line is recognized, any accumulated references are flushed out. N either .r1 nor .r2 lines, nor anything 
between them, is output. 





Commands are separated by newlines or semicolons. # introduces a comment that extends to the end of the line (but does 
not conceal the newline). Each command is broken up into words. W ords are separated by spaces or tabs. A word that begins 
with an open quote (“) extends to the next close quote (”) that is not followed by another open quote (“). If there isno such 
open quote (“) the word extends to the end of the line. Pairs of open quotes (“) in a word beginning with collapse to a single 
open quote (“). Neither # nor ; is recognized inside open quotes (“). A line can be continued by ending it with \; this works 
everywhere except after a #. 


Each command name that ismarked with « hasan associated negative command no-name that undoes the effect of name. For 
example, the no-sort command specifies that references should not be sorted. T he negative commands take no arguments. 


oo 


In the following description, each argument must be a single word; fie! d is used for a single uppercase or lowercase letter 
naming afield; fields is used for asequence of such letters; m and n are used for a nonnegative numbers; string is used for an 
arbitrary string; fil ename is used for thename of afile 


abbreviate*fieldsstring1 


string2string3string4 


abbreviate-label-ranges*string 


accumulate* 


annotate*fieldstring 


articlesstring ... 
string ... 


bibliographyfilename ... 


bracket-labelstring 
Istring2string3 


capitalizefiel ds 


compatible* 


databasefilename... 


date-as-label*string 


default -database* 


Abbreviate the first names of fi el ds. An initial letter will be separated from another 
initial letter by st ring1, from thelast name by string2, and from anything else (such 
aS a von Or de) bystring3. 7 hese default to a period followed by a space Ina 
hyphenated first name, the initial of the first part of the name will be separated from 
the hyphen by string4; this defaults to aperiod. N o attempt is madeto handle any 
ambiguities that might result from abbreviation. N ames are abbreviated before 
sorting and beforelabel construction. 

Three or more adjacent labels that refer to consecutive references will be abbreviated 
to alabel consisting of the first label, followed by string, followed by the last label. 
This is mainly useful with numevic labds. If string is omitted it defaults to -. 


Accumulate references instead of writing out each reference as it is encountered. 
Accumulated references will be written out whenever a reference of the form: 

[ 
$LIST$ 
+] 


is encountered, after all input files have been processed, and whenever an .r1 line is 
recognized. 

field isan annotation; print it at the end of the reference as a paragraph preceded by 
the line 

string 

If macro is omitted, it will default to ap;if fie1d is also omitted, it will default to x. 
Only one field can bean annotation. 

T hese are definite or indefinite articles, and should be ignored at the beginning of T 
fidds when sorting. Initially, the, a, and an are recognized as articles. 


W rite out all the references contained in the bibliographic databasestilename ... 

In the text, bracket each label with string1 and string2. An occurrence of st ring2 
immediately followed by string1 will be turned into string3. T he default behavior is 
bracket-label \*([. \*(.] “, “ 

Convert fields to caps and small caps. 


Recognize .R1 and .r2 even when followed by a character other than space or 
newline 

Search the bibliographic databasesti|ename... For each filename if an index 
filename .i created by gindxbib(1) exists, then it will be searched instead; each index 
can cover multiple databases. 

string iSalabel expression that specifies a string with which to replace the p fidd 
after constructing the label. See “Label Expressions,” later in this manual page, for a 
description of label expressions. This command is useful if you do not want explicit 
labels in the referencelist, but instead want to handle any necessary disambiguation 
by qualifying the date in some way. The label used in the text would typically be 
some combination of the author and date. |n most cases, you should also use the no- 
label-in-reference command. For example, 
date-as-label D.+yD.y%a*D.-y 

would attach adisambiguating letter to the year part of theo field in the reference 


The default database should be searched. T his is the default behavior, so the negative 
version of this command is more useful. refer determines whether the default 
database should be searched on the first occasion that it needs to do a search. Thus, a 
no-default-database command must be given before then, in order to be effective 
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discard*fiel ds 


et-al*stringmn 


includefi| ename 


join-authorsstring] 
string2string3 


label-in-reference* 


label-in-text* 


labelstring 


separate -label-second-parts 
string 


move -punctuation* 
reverse*string 


search-ignore*fi el ds 


search-truncate*n 


short -label*string 
sort*string 


sort-adjacent-labels* 


W hen the reference is read, fi el ds should be discarded; no string definitions for 
fields will be output. Initially, fields are xyz. 

Control use of et al in the evaluation of @ expressions in 1abe1 expressions. If the 
number of authors needed to make the author sequence unambiguous isu and the 
total number of authorsist, then thelastt - uv authors will be replaced by string, 
provided thatt - u isnot lessthan mandt isnot less than n. The default behavior is 
et-al " et al" 23 

Includetilename and interpret the contents as commands. 

This says how authors should be joined together. W hen there are exactly two 
authors, they will be joined with string1. When there are more than two authors, all 
but the last two will be joined with string2, and the last two authors will be joined 
with string3. Ifstring3 is omitted, it will default to string1;ifstring2 isalso 
omitted, it will also default to string1. For example 

join-authors " and" ", " ", and " 

will restore the default method for joining authors. 


W hen outputting the reference, define the string [F to be the reference’s labd. T his 
is the default behavior; so the negative version of this command is more useful. 

For each reference output a labd in the text. The labd will be separated from the 
surrounding text as described in the bracket -1label command. T hisis the default 
behavior; so the negative version of this command is more useful. 


string iSalabel expression describing how to label each reference 


W hen merging two-part labd’s, separate the second part of the second label from the 
first label with string. See the description of the <> label expression. 

In the text, move any punctuation at the end of line past the label. It is usually a 
good idea to give this command unless you are using superscripted numbers as 
labds. 

Reverse the fidds whose names are in string. Each fidd name can be followed by a 
number that says how many such fidds should be reversed. If no number is given for 
a fidd, all such fields will be reversed. 

W hile searching for keys in databases for which no index exists, ignore the contents 
of fields. Initially, fidds xyz are ignored. 

Only require the firstn characters of keys to be given. In effect, when searching for a 
given key, words in the database are truncated to the maximum of n and the length 
of the key. Initially, n ise. 

string iSalabel expression that specifies an alternative (usually shorter) style of labd. 
Thisis used when the # flag is given in the citation. When using author-date style 
labels, the identity of the author or authors is sometimes clear from the context, and 
so it may be desirable to omit the author or authors from the label. The short - label 
command will typically be used to specify alabel containing just a date and possibly 
a disambiguating letter. 

Sort references according to string. References will automatically be accumulated. 
string Should be alist of fidd names, each followed by anumbe,, indicating how 
many fields with the name should be used for sorting. + can be used to indicate that 
all the fidds with the name should be used. Also, . can be used to indicate the 
references should be sorted using the (tentative) label. (The “Label Expressions” 
subsection describes the concept of a tentative label.) 

Sort labels that are adjacent in the text according to their position in the reference 
list. This command should usually be given if the abbreviate-label-ranges 
command has been given, or if the label expression containsa <> expression. This 
will have no effect unless references are being accumulated. 





LABEL EXPRESSIONS 


mo 


Label expressions can be evaluated both normally and tentatively. The result of normal evaluation is used for output. The 
result of tentative evaluation, called the tentative label, is used to gather the information that normal evaluation needs to 
disambiguate the labd. Label expressions specified by the date-as-label and short-label commands are not evaluated 
tentatively. N ormal and tentative evaluation are the same for all types of expression other than e, «, and % expressions. The 
following description applies to normal evaluation, except where otherwise specified. 


field, field n 


"string! 





@ 

Sn, %a, %A, Si, 61 
expr* 

expr+n, expr-n 
expr.1 

expr .u 

expr .c 

expr .r 

expr.a 

expr.y 

expr.ty 

expr .-y 

expr.n 
exprlexpr2 
exprl expr2 
exprljexpr2 
exprl&expr2 
exprl?expr2 :expr3 


<expr> 


Thenth part of fidd. If n isomitted, it defaults to 1. 

The characters in string literally. 

All the authors joined as specified by the join-authors command. The whole of each author’s name 
will be used. H owever, if the references are sorted by author (that is the sort specification starts with 
A+), then authors’ last names will be used instead, provided that this does not introduce ambiguity, and 
also an initial subsequence of the authors may be used instead of all the authors, again provided that 
this does not introduce ambiguity. T he use of only the last name for thei -th author of some reference 
is considered to be ambiguous if there is some other reference such that thefirst i - 1 authorsof the 
references are the same, the i-th authors are not the same, but the i-th authors’ last names are the 
same. A proper initial subsequence of the sequence of authors for some reference is considered to be 
ambiguous if there is a reference with some other sequence of authors that also has that subsequence as 
a proper initial subsequence W hen an initial subsequence of authorsis used, the remaining authors are 
replaced by the string specified by the et-al command; this command may also specify additional 
requirements that must be met before an initial subsequence can be used. @ tentatively evaluates to a 
canonical representation of the authors, such that authors that compare equally for sorting purpose will 
have the same representation. 

Theserial number of the reference formatted according to the character following thes. T he serial 
number of areferenceis 1 plus the number of earlier references with same tentative label as this 
reference. T hese expressions tentatively evaluate to an empty string. 

If there is another reference with the same tentative label as this reference, then expr; otherwise, an 
empty string. It tentatively evaluates to an enpty string. 

The first (+) or last (-) n uppercase or lowercase letters or digits of expr. troff special characters (such 
as \('a) count as a single letter. Accent strings are retained but do not count toward the total. 

expr converted to lowercase. 

expr converted to uppercase. 

expr converted to caps and small caps. 

expr reversed so that the last name is first. 

expr with first names abbreviated. N ote that fidds specified in the abbreviate command are abbrevi- 
ated before any labels are evaluated. Thus .a is useful only when you want a fidd to be abbreviated in a 
label but not in a reference. 

The year part of expr. 

The part of expr before the year, or the whole of expr if it does not contain a year. 

Thepart of expr after the year, or an empty string if expr doesnot contain a year. 

The last name part of expr. 

expr except that if the last character of expr1 is - then it will be replaced by expr2. 

The concatenation of expr1 and expr2. 

If expr1 isnonempty, then expr1; otherwise, expr2. 

If expr1 isnonempty, then expr2; otherwise, an empty string. 

If expr1 isnonempty, then expr2; otherwise, expr3. 

The label isin two parts, which are separated by expr. T wo adjacent two-part labels that havethe same 
first part will be merged by appending the second part of the second labd onto the first label separated 
by the string specified in the separate -1abel-second-parts Command (initially, a comma followed by a 
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space); the resulting label will also be a two-part label with the same first part as before merging, and so 
additional labed's can be merged into it. N ote that it is permissible for the first part to be empty; this 
may be desirable for expressions used in the short-1abel command. 


(expr) Thesame as expr. U sed for grouping. 
The preceding expressions are listed in order of precedence (highest first); and | have the same precedence 


MACRO INTERFACE 


Each reference starts with a call to the macro }-. T hestring [F will be defined to be the labd for this reference unless the no- 
label-in-reference Command has been given. T here then follows a series of string definitions, one for each field: string [x 
corresponds to field x. Thenumber register [P is set to 1 if the p fidd contains a range of pages. The [T, [A, and [o number 
registers are set to 1 according as thet, a, and 0 fidds end with one of the characters .7!. The [£ number register will be set 
to 1 if the [e string contains more than onename The reference is followed by a call to the }{ macro. Thefirst argument to 
this macro gives anumber representing the type of the reference. If a reference contains au fidd, it will be classified as type 1; 
otherwise if it containsas fidd, it will be type 3; otherwise, if it containsaG or R fidd it will be type 4, otherwise if it 
contains an 1 field, it will be type 2; otherwise, it will be type 0. The second argument is asymbolic name for the type other, 
journal-article, book, article-in-book, Or tech-report. Groups of references that have been accumulated or are produced by 
the bibliography command are preceded by a call to the }< macro and followed by a call to the }> macro. 


FILES 
/usr/dict/papers/Ind D efault database 
file.i Index files 

SEE ALSO 
gindxbib(1), glookbib(1), 1kbib(1) 

BUGS 


In label expressions, <> expressions are ignored inside .char expressions. 
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grep, egrep, fgrep 


grep, egrep, fgrep— Print lines matching a pattern 


SYNOPSIS 
grep [ -[[AB]]num ][-[CEFGVBchilnsvwx]][-e ] pattern j -ffile ][files... ] 
DESCRIPTION 


grep searches the named input files (or standard input if no files are named, or the filename - is given) for lines containing a 
match to the given pattern. By default, grep prints the matching lines. 


There are three major variants of grep, controlled by the following options: 


-G Interpret pattern aS abasic regular expression (see the list following this one). This isthe default. 
-E Interpret pattern aS an extended regular expression. 
-F Interpret pattern aS alist of fixed strings, separated by newlines, any of which is to be matched. 


In addition, two variant programs, egrep and fgrep, are available. egrep issimilar (but not identical) to grepn-e, and is 
compatible with the historical UNIX egrep. Fgrep isthe same as grepn-F. 


All variants of grep understand the following options: 


grep, egrep, fgrep [= | 


num M atches will be printed with num lines of leading and trailing context. H owever, grep will never print 
any given line more than once. 

-A num Print num lines of trailing context after matching lines. 

-B num Print num lines of leading context before matching lines. 

-C Equivalent to -2. 

-V Print the version number of grep to standard error. T his version number should be included in all bug 
reports. 

-b Print the byte offset within the input file before each line of output. 

-c Suppress normal output; instead print a count of matching lines for each input file. With the-v 
option, count nonmatching lines. 

-e pattern Usepattern asthe pattern; useful to protect patterns beginning with -. 

-f file O btain the pattern from file. 

-h Suppress the prefixing of filenames on output when multiple files are searched. 

-i Ignore case distinctionsin both the pattern and the input files. 

-L Suppress normal output; instead print the name of each input file from which no output would 
normally have been printed. 

-1 Suppress normal output; instead print the name of each input file from which output would normally 
have been printed. 

-n Prefix each line of output with theline number within its input file 

-q Quiet; suppress normal output. 

-§ Suppress error messages about nonexistent or unreadable files. 

-v Invert the sense of matching, to select nonmatching lines. 

-w Sdect only those lines containing matches that form whole words. T he test is that the matching 


substring must ether be at the beginning of the line, or preceded by anonword constituent character. 
Similarly, it must be ther at the end of the line or followed by anonword-constituent character. 
W ord-constituent characters are letters, digits, and the underscore. 


-x Sdect only those matches that exactly match the whole line. 


REG ULAR EXPRESSIONS 


A regular expression is a pattern that describes a set of strings. Regular expressions are constructed analogously to arithmetic 
expressions, by using various operators to combine smaller expressions. 


grep understands two different versions of regular expression syntax: badc and extended. In GN U\grep, there is no difference 
in available functionality using either syntax. In other implementations, basic regular expressions are less powerful. T he 
following description applies to extended regular expressions; differences for basic regular expressions are summarized 
afterwards. 


The fundamental building blocks are the regular expressions that match a single character. M ost characters, including all 
letters and digits, are regular expressions that match themsdves. Any meta character with special meaning may be quoted by 
preceding it with a backslash. 


A list of characters enclosed by [ and } matches any single character in that list; if the first character of the list is the caret (*) 
then it matches any character not in the list. For example the regular expression [0123456789] matches any single digit. A 
range of ASCII characters may be specified by giving the first and last characters, separated by a hyphen. Finally, certain 
named classes of characters are predefined. Thar names are self-explanatory, and they are[:alnum:], [:alpha:], [:cntrl:], 
[:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:]. For example, [[:alnum: ]] 
means [@-9A-Za- z], except the latter form is dependent upon the ASCII character encoding, whereas the former is portable. 
(N ote that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets 
ddimiting the bracket list.) M ost meta characters lose thar special meaning inside lists. To include a literal j, place it first in 
the list. Similarly, to include a literal ~, place it anywhere but first. Finally, to include a literal --, place it last. 


The period matches any single character. The symbol \w isasynonym for [[:alnum:]] and \wisasynonym for [*[:alnum]]. 
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The caret and the dollar sign are meta characters that respectivdy match the empty string at the beginning and end of aline. 
Thesymbols \< and \>, respectivay, match the empty string at the beginning and end of aword. Thesymbol \b matchesthe 
empty string at the edge of aword, and \B matches the empty string provided it’s not at the edge of a word. 


A regular expression matching a single character may be followed by one of several repetition operators: 


2 The preceding item is optional and matched at most once 

* The preceding item will be matched zero or more times. 

+ The preceding item will be matched one or more times. 

n The preceding item is matched exactly n times. 

n, The preceding item is matched n or more times. 

,m The preceding item is optional and is matched at most m times. 

nym The preceding item is matched at least n times, but not more than m times. 











Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating 
two substrings that respectivey match the concatenated subexpressions. 


Two regular expressions may be joined by the infix operator |; the resulting regular expression matches any string matching 
either subexpression. 


Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole subexpression may 
be enclosed in parentheses to override these precedence rules. 


The back reference \n, wheren isasingle digit, matches the substring previously matched by then th parenthesized 
subexpression of the regular expression. 


In basic regular expressions, the meta characters !, (, and ) lose their special meaning; instead use the backslashed versions 
\2, \t, \f, Vj, VG, and \). 


In egrep, the meta character , loses its special meaning; instead use \{. 


DIAGNOSTICS 


Normally, exit status is if matches were found, and 1 if no matches were found. (The .B -v option inverts the sense of the 
exit status.) Exit status is 2 if there were syntax errors in the pattern, inaccessible input files, or other system errors. 


BUGS 
E-mail bug reports to bug-gnu-utils@prep.ai.mit.edu. Be sure to include the word grep somewhere in the “Subject:” fidd. 


Large repetition counts in them ,n construct may cause grep to use lots of manory. In addition, certain other obscure regular 
expressions require exponential time and space, and may cause grep to run out of memory. 


Back references are very slow, and may require exponential time 
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grephistory 
grephistory— Display filavames from U senet history file 


SYNOPSIS 


grephistory [ -f filename ][-e ][-n ][-q ][-1 ][-i ][-s ][messageid ] 


DESCRIPTION 
grephistory queries the dbz(3) index into the history(5) file for an article having a specified M essage ID. 


If messageid cannot be found in the database, the program prints “N ot found” and exits with anonzero status. If messageid is 
in the database, the program prints the pathname and exits successfully. If no pathname exists, the program will print /dev/ 


grodvi 227 


null and exit successfully. Thiscan happen when an article has been canceled, or if it has been expired but its history is still 
retained. T his is default behavior, which can be obtained by using the -n flag. 


If the -q flag is used, then no message is displayed. The program will still exit with the appropriate exit status. If the -e flag is 
used, then grephistory will only print the filename of an existing article 


If the -1 flag isused, then the entire line from the history file will be displayed. 


If the -i flag isused, then grephistory will read alist of Message 1D son standard input, one per line Leading and trailing 
whitespace is ignored, as are any malformed lines. It will print on standard output those M essageD s that are not found in 
the history database. T his flag is used in processing ihave control messages. 


If the -s flag isused, then grephistory will read asimilar list from its standard input. It will print on standard output a list of 
filenames for each article that is still available. T his flag is used in processing sendme control messages. 

















To specify a different value for the history file and database, use the -+ flag. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


dbz(3), history(5) 


grodvi 


grodvi— Convert groff output to T eX dvi format 


SYNOPSIS 


grodvi [ -dv ][-wn ][-Fdir ][files ... ] 


DESCRIPTION 


grodvi iSa driver for groff that produces dvi format. Normally, it should be run by groff-Tdvi. This will run gtroff-Tdvi; it 
will also input the macros /usr/1lib/groff/tmac/tmac.dvi; if theinput is being preprocessed with geqn, it will also input /usr/ 
lib/groff/font/devdvi/eqnchar. 


The avi file generated by grodvi can be printed by any correctly written dvi driver. The troff drawing primitives are 
implemented using the tpic version 2 specials. If the driver does not support these the \p commands will not produce any 
output. 


Thereisan additional drawing command available 


\D'Rdh dv’ D raw arule (solid black rectangle), with onecorne at the current position, and the diagonaly 
opposite corner’ at thecurrent position +(dh ,dv). Afterwards, the current position will be at the 
opposite corne. This produces a rulein the dvi file and so can be printed even with a driver that does 
not support the tpic specials, unlike the other \p commands. 


The groff command \x'anything ' iStranslated into the same command in the avi file as would be produced by \special{ 
anything } in T eX; anything may not contain a newline. 





Font files for groavi can be created from tfm files using tfmtodit(1). The font description file should contain the following 
additional commands: 


internalname name Thenameof the tfm file (without the .tfm extension) iSname. 
checksum n The checksum in the tfm file isn. 
designsize n The designsize in thetfm fileisn. 


T hese are automatically generated by tfmtodit. 
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In troff, the \n escape sequence can be used to access characters by their position in the corresponding tfm file all characters 
in the tfm file can be accessed this way. 


OPTIONS 
-d Do not use tpic specials to implement drawing commands. H orizontal and vettical lines will be implemented by 
rules. O ther drawing commands will be ignored. 
-v Print the version number. 
-wn Sé& the default line thickness to n thousandths of an en. 
-Fdir Search directory dir /devavi for font and device description files. 
FILES 
/usr/1ib/groff/font/devdvi/DESC D evice description file 
/usr/lib/groff/font/devdvi/ F Font description file for font F 
/usr/lib/groff/tmac/tmac.dvi M acrosfor use with grodvi 
BUGS 


dvi files produced by grodvi use a different resolution (57,816 units per inch) than those produced by T eX. Incorrectly 
written drivers that assume the resolution used by T eX, rather than using the resolution specified in theavi file, will not 
work with grodvi. 


When using the -a option with boxed tables, vertical and horizontal lines can sometimes protrude by one pixd. Thisisa 
consequence of the way T eX requires that the haghts and widths of rules be rounded. 


SEE ALSO 


tfmtodit(1), groff(1), gtroft(1), geqn(1), groff_out(5), groff_font(5), groff_char(7) 
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grotf 
groff— Front end for the grott document formatting systen 


SYNOPSIS 


groff [ -tpeszaivhblCENRVXZ][-wname ][-Wname ][-mname ][-Fdir ][-Tdev ] [ -ffam ][-Mdir ][-des ][-rcn ][-nnum ] 
[-olist ][-Parg ][files ... ] 


DESCRIPTION 


groff isafront-end to the grott document formatting system. N ormally, it runs the gtroff program and a postprocessor 
appropriate for the selected device. Available devices are 


ps For PostScript printers and previewers 
dvi For TeX dvi format 
X75 Fora75 dpi X11 previewer 


X100 For al00dpi X11 previewe 

ascii For typewriter-like devices 

latint For typewriter-like devices using the!SO Latin-1 character set. 

The postprocessor to be used for a deviceis specified by the postpro command in the device description file. This can be 
overridden with the -x option. 


The default device is ps. It can optionally preprocess with any of gpic, geqn, gtbl, grefer, OF gsoelim. 


O ptions without an argument can be grouped behind a single -. A filename of - denotes the standard input. 
The grog command can be used to guess the correct groff command to use to format a file. 


OPTIONS 
-h Print ahap message. 
-e Preprocess with geqn. 
=t Preprocess with gtb1. 
-p Preprocess with gpic. 
-s Preprocess with gsoelim. 
-R Preprocess with grefer. No mechanism is provided for passing arguments to grefer because most grefer options 
have equivalent commands that can be included in the file. See grefer(1) for more details. 
-v M ake programs run by groff print out thar version number. 
-V Print the pipeline on stdout instead of executing it. 
-2 Suppress output from gtroff. O nly error messages will be printed. 
-Z Do not postprocess the output of gtroff. Normally, grof# will automatically run the appropriate postprocessor. 


-Parg Passarg to the postprocessor. Each argument should be passed with a separate -p option. N ote that groff does not 
prepend - to arg before passing it to the postprocessor. 


-1 Send the output to a printer. The command used for this is specified by the print command in the device 
description file 


-Larg Passarg to the spooler. Each argument should be passed with a separate -L option. N ote that groff does not 
prepend - to arg before passing it to the postprocessor. 


-Tdev Prepare output for devicedev. The default device is ps. 


-X Preview with gxditview instead of using the usual postprocessor. Thisis unlikely to produce good results exceot 
with -Tps. 
-N Don’t allow newlines with eqn ddimiters. This is the same as the -n option in geqn. 


The options -a, -b, -i, -C, -E, -wname, -Wname, -mname, -olist, -des, -rcn, -Fdir, -Mdir, -ffam, and -nnum are described in 
gtroff(1). 
ENVIRONMENT 


GROFF_COMMAND PREFIX If thisis set x, then groff will run xtroff instead of gtroff. This also applies to tb1, pic, eqn, refer, 
and soelim. It does not apply to grops, grodvi, grotty, and gxditview. 


GROFF_TMAC_PATH A colon-separated list of directories in which to search for macro files. 

GROFF_TYPESETTER D efault device 

GROFF_FONT_PATH A colon-separated list of directories in which to search for the devname directory. 

PATH The search path for commands executed by groff. 

GROFF_TMPDIR The directory in which tenporary files will be created. If this is not set and Tupprr isset, temporary 


files will be created in that directory. O therwise temporary files will be created in /tmp. The 
grops(1) and grefer(1) commands can create temporary files. 


FILES 
/usr/1ib/groff/font/devname /DESC D evice description file for devicename 
/usr/lib/ groff/font/devname/F Font file for font F of davicename. 
AUTHOR 


James Clark (jjc@jclark.com) 
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BUGS 
Report bugs to bug-groff@prep.ai.mit.edu. Include a complete, saf-contained example that will allow the bug to be 
reproduced, and say which version of groff you are using. 

COPYRIGHT 
Copyright 1989, 1990, 1991, 1992 Free Software Foundation, Inc. 


groff iSfree software you can redistribute it or modify it under theterms of theG NU G eneral Public License as published 
by the Free Software Foundation; either version 2, or (at your option) any later version. 


groff iS distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of 
merchantability or fitness for a particular purpose. See the GNU General Public License for more détails. 


You should have received a copy of the GNU Geeral Public License along with groff; see the file copyine. If not, write to 
the Free Software Foundation, 675 M ass Ave, Cambridge MA 02139, USA. 

AVAILABILITY 
The most recent released version of groff is always available for anonymous ftp from prep.ai.mit.edu (18.71.0.38) in the 
directory pub/gnu. 

SEE ALSO 


grog(1), gtroft(1), gtb1(1), gpic(1), geqn(1), gsoelim(1), grefer(1), grops(1), grodvi(1), grotty(1), gxditview(1), 
groff_font(5), grof_out(5), groff_ms(7), groftt_me(7), groff_char(7) 
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grog 


grog— Guess options for groff command 


SYNOPSIS 


grog [ -option ...][files ... ] 


DESCRIPTION 


grog readsfiles and guesses which of the groft(1) options -e, -man, -me, -mm, -ms, -p, -s,and -t are required for printing 
files, and prints the groff command including those options on the standard output. A filename of - is taken to refer to the 
standard input. If no files are specified, the standard input will be read. Any specified options will be included in the printed 
command. N o space is allowed betwee options and thar arguments. For example, 


‘grog -Tdvi paper.ms' 
will guess the appropriate command to print paper.ms and then run it after adding the -Tavi option. 
SEE ALSO 
doctype(1), groff(1), gtroftt(1), gtb1(1), gpic(1), geqn(1), gsoelim(1) 
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grops 


grops— PostScript driver for groft 


SYNOPSIS 


grops [ -glv ][-bn ][-cn ][-wn ][-Fdir ][files ... ] 


= OF 
DESCRIPTION 


grops translates the output of GNU troff to PostScript. N ormally, grops should be invoked by using the groff command 
with a -Tps option. If no files are given, grops will read the standard input. A filename of - will also cause grops to read the 
standard input. PostScript output is written to the standard output. When grops isrun by groff, options can be passed to 
grops by using the groff -P option. 


OPTIONS 


-bn Work around broken spoolers and previewers. N ormally grops produces output that conforms the Document 
Structuring C onventions version 3.0. Unfortunately, some spoolers and previewers can’t handle such output. The 
value of n controls what grops does to its output acceptable to such programs. A value of @ will cause grops not to 
employ any workarounds. Add 1 if no %%BeginDocumentSetup and %%EndDocumentSetup comments should be 
generated; thisis needed for early versions of T ranScript that get confused by anything between thes%endProlog 
comment and the first %%Page comment. Add 2 if linesin included files beginning with %! should be stripped out; 
thisis needed for Sun’s pageview previewer. Add 4 if s%Page, %*Trailer, aNd %%sEndProlog comments should be 
stripped out of included files; this is needed for spoolers that don’t understand the x«BeginDocument and 

’EndDocument comments. Add s if the first line of the PostScript output should be %!Ps-Adobe-2.0 rather than 

IPS -Adobe-3.0; thisis needed when using Sun’s N ewsprint with a printer that requires page reversal. T he default 
value can be specified by abrokenn Command in thepesc file. O therwise, the default value is 0. 

-cn Print n copies of each page. 


-g Guess the page length. T his generates PostScript code that guesses the page length. T he guess will be correct only 
if the imageable area is vertically centered on the page This option allows you to generate documents that can be 
printed both on letter (8.5x11) paper and on A4 paper without change 


oe 


oe 








-1 Print the document in landscape format. 
-Fdir Search the directory dir /devname for font and device description files; name is the name of the device, usually ps. 
-wn Lines should be drawn using a thickness of n thousandths of an em. 
-v Print the version number. 
USAGE 


There are styles called r, 1, 8, and B1 mounted at font positions 1 to 4. The fonts are grouped into families a, BM, Cc, H, HN, N, 
Pp, and T having members in each of these styles: 


AR AvantG arde-B ook 

AI AvantG arde-BookO blique 
AB AvantG arde-D emi 

ABI AvantG arde-D emiO blique 
BMR Bookman-Light 

BMI Bookman-Lightltalic 

BMB Bookman-D emi 

BMBI Bookman-D emiltalic 

CR Courier 

CI Courier-O blique 

CB Courier-Bold 

CBI C ourier-BoldO blique 

HR H elvetica 

HI H elvetica-O blique 

HB H elvetica-Bold 

HBI H elvetica-BoldO blique 
HNR H elvetica-N arrow 


HNI H elvetica-N arrow-O blique 
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HNB H elvetica-N arrow-Bold 

HNBI H elvetica-N arrow-BoldO blique 
NR N ewC enturySchlbk-Roman 
NI N ewC enturySchlbk-Italic 

NB N ewC enturySchibk-Bold 

NBI N ewC enturySchlbk-Boldl talic 
PR Palatino-Roma 

PI Palatino-Italic 

PB Palatino-Bold 

PBI Palatino-Bolditalic 

TR Times-Roman 

TI Times-Italic 

TB Times-Bold 

TBI Times-Boldltalic 


There is also the following font which is not amember of a family: 


ZCMI ZapfC hancery-M ediumitalic 


There are also some special fonts called ss and s. Zapf D ingbatsis available as zp and a reversed version of ZapfD ingbats 
(with symbols pointing in the opposite direction) is available as zor; most characters in these fonts are unnamed and must be 


accessed using \N. 


grops understands various x commands produced using the \x escape sequence grops will only interpret commands that 


begin with aps: tag. 


\X'ps:exec code’ 


\X'ps:fil ename’ 
\X'ps:def code’ 


This executes the arbitrary PostScript commands in code. The PostScript currentpoint will be set to 
the position of the \nx command before executing code. T he origin will be at the top left corner of 
the page, and y coordinates will increase down the page. A procedure u will be defined that converts 
groff units to the coordinate system in effect. For example, 

\X'ps: exec \nx u @ rlineto stroke' 

will draw a horizontal line oneinch long. code may make changesto the graphics state but any 
changes will persist only to the end of the page A dictionary containing the definitions specified by 
def and mdef will be on top of the dictionary stack. If your code adds definitions to this dictionary, 
you should allocate space for them using \x'psmdefn'. Any definitions will persist only until the end 
of the page. If you use the \y escape sequence with an argument that names a macro, code can 
extend over multiple lines. For example, 

nr x ti 

de y 

ps: exec 

\nx u @ rlineto 

stroke 


\Yy 

is another way to draw a horizontal line one inch long. 

This is the same as the exec command except that the PostScript code is read from filename. 
Place a PostScript definition contained in code in the prologue. T here should be at most one 
definition per \x command. Long definitions can be split over several \x commands; all the code 
arguments are simply joined together separated by newlines. T he definitions are placed in a 
dictionary which is automatically pushed on the dictionary stack when an exec command is 


executed. If you use the \Y escape sequence with an argument that names a macro, code can extend 
over multiple lines. 


= Om 


\X'ps:mdef ncode ' Like def, except that code may contain up to n definitions. grops needs to know how many 
definitions code contains so that it can create an appropriately sized PostScript dictionary to contain 
them. 

\X'ps:importfile Import a PostScript graphic from file. The arguments 11x, 11y, urx, and ury give the bounding box 

11xllyurxurywidth of the graphic in the default PostScript coordinate system; they should all be integers; 11x and 11y 

[height]' are the x and y coordinates of the lowe-left corner of the graphic; urx and ury are the x and y 


coordinates of the upper-right corner of the graphic; width and height are integers that give the 
desired width and height in groff units of the graphic. The graphic will be scaled so that it has this 
width and height and translated so that the lower-left corner of the graphic is located at the 
position associated with \x command. If theheight argument is omitted, it will be scaled uniformly 
in thex and y directions so that it has the specified width. N ote that the contents of the \x 
command are not interpreted by troft; so vertical space for the graphic is not automatically added, 
and thewidth and height arguments are not allowed to have attached scaling indicators. If the 
PostScript file complies with the Adobe D ocument Structuring Conventions and containsa 
%%BoundingBox Comment, then the bounding box can be automatically extracted from within grotf 
by using the sy request to run the psbb command. 


The -mps macros (which are automatically loaded when grops isrun by the groff command) include a psprc macro that 
allows a picture to be easily imported. T his has the format: 


.PSPIC file [ -L j -R j -I n ][width [ height ]] 


file isthe name of the file containing the illustration; width and hei ght give the desired width and height of the graphic. The 
width and height arguments may have scaling indicators attached; the default scaling indicator is i. This macro will scale the 
graphic uniformly in the x and y directions so that it isno more than width wide and hei ght high. By default, the graphic will 
be horizontally centered. The -L and -r cause the graphic to be left-aligned and right-aligned, respective y. T he -1 option 
causes the graphic to be indented by n. 


\X'ps: invis', \X'ps: endinvis' No output will be generated for text and drawing commands that are bracketed with 
these\X commands. T hese commands are intended for use when output from trot will 
be previewed before being processed with grops; if the previewer is unable to display 
certain characters or other constructs, then other substitute characters or constructs can 
be used for previewing by bracketing them with these \x commands. 


For example, gxditview isnot able to display a proper \ (em character because the standard X11 fonts do not provideit; this 
problem can be overcome by executing the following request: 


-char \(em \X'ps: invis' \ 

\Z'\v'-.25m'\h'.05m'\D'1 .9m O'\h'.e5m"\ 

\X'ps: endinvis'\(em 

In this case, gxditview will be unable to display the \ (em character and will draw theline whereas grops will print the \ (em 
character and ignore the line. 

The input to grops must bein the format output by gtrof#(1). Thisis described in groff_out(1). In addition, the device and 
font description files for the device used must meet certain requirements. T he device and font description files supplied for 
ps device meet all these requirements. afmtodit(1) can be used to create font files from arm files. The resolution must be an 
integer multiple of 72 times the sizescale. The ps device uses a resolution of 72000 and a sizescale of 1000. The device 
description file should contain a command: 


paperlengthn 


which says that output should be generated that is suitable for printing on a page whose length isn machineunits. Each font 
description file must contain a command: 


internalnameps name 


which says that the PostScript name of the font ispsname. It may also contain acommand: 


encodingenc file 
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which says that the PostScript font should be reencoded using the encoding described in enc_file; thisfile should consist of a 
sequence of lines of the form: 


pschar code 


where pschar is the PostScript name of the character, and code isits position in the encoding expressed as a decimal integer. 
The code for each character given in the font file must correspond to the code for the character in encoding file, or to the 
code in the default encoding for the font if the PostScript font is not to be reencoded. T his codecan be used with the \n 
escape sequence in troff to sdect the character, even if the character does not have a groff name. Every character in the font 
file must exist in the PostScript font, and the widths given in the font file must match the widths used in the PostScript font. 
grops will assume that a character with a groff name of space is blank (makes no marks on the page); it can make use of such 
a character to generate more efficient and compact PostScript output. 


grops Can automatically include the downloadable fonts necessary to print thedocument. Any downloadable fonts which 
should, when required, be included by grops must be listed in the file /usr/1ib/groff/font/devps/download; this should 
consist of lines of the form: 


font filename 


wherefont isthe PostScript name of the font, and fi! ename is the name of the file containing the font; lines beginning with # 
and blank lines are ignored; fidds may be separated by tabs or spaces; fi | ename will be searched for using the same mecha- 
nism that is used for groff font metric files. The download file itself will also be searched for using this mechanism. 


If the file containing a downloadable font or imported document conforms to the Adobe D ocument Structuring C onven- 
tions, then grops will interpret any comments in the files sufficiently to ensure that its own output is conforming. It will also 
supply any needed font resources that are listed in the download file as well as any needed file resources. It is also able to 
handle interresource dependencies. For example, suppose that you have a downloadable font called Garamond, and also a 
downloadable font called Garamond-O utline that depends on Garamond (typically, it would be defined to copy Garamond’s 
font dictionary, and change the PaintT ype), then it is necessary for Garamond to appear before Garamond-O utline in the 
PostScript document. grops will handle this automatically provided that the downloadable font file for G aramond-O utline 
indicates its deoendence on Garamond by means of the D ocument Structuring Conventions, for example by beginning with 
the following lines: 

%\PS-Adobe-3.@ Resource-Font 

%sDocumentNeededResources: font Garamond 


“sEndComments 
%%IncludeResource: font Garamond 


oe 


In this case, both Garamond and Garamond-O utline would need to be listed in the download file A downloadable font 
should not include its own name in a%%DocumentSuppliedResources comment. 


grops will not interpret %%DocumentFonts comments. 


T he %%DocumentNeededResources, %%DocumentSuppliedResources, %%*IncludeResource, %%BeginResource, and %%EndResource 
comments (or possibly the old %%DocumentNeededFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%BeginFont, and %%EndFont 
comments) should be used. 





FILES 
/usr/lib/groff /font/devps/DESC D evice description file 
/usr/lib/groff /font/devps/F Font description file for font F 
/usr/1lib/groff /font/devps/download List of downloadable fonts. 
/usr/1lib/groff/font/devps/text.enc Encoding used for text fonts 
/usr/lib/groff /tmac/tmac.ps M acrosfor use with grops; automatically loaded by troffre 
/usr/lib/groff/tmac/tmac.pspic Definition of psp1c macro, automatically loaded by tmac.ps 
/usr/lib/groff/tmac/tmac.psold M acrosto disable use of characters not present in older PostScript printers; 
automatically loaded by tmac.ps 
/usr/lib/groff/tmac/tmac.psnew M acrosto undo the effect of tmac.psold 


/tmp / gropsXXXXXX Temporary file 


grotty [= | 


Groff Veron 1.09, 14 February 1995 


SEE ALSO 


afmtodit(1), groff(1), gtroff(1), psbb(1), groff_out(5), groff_font(5), groff_char(7) 


grotty 


grotty— groff driver for typewriter-like devices 


SYNOPSIS 


grotty [ -hfbuodBUv ][-Fdir ][files ... ] 


DESCRIPTION 


grotty translates the output of GN U troff into aform suitable for typewriter-like devices. Normally, grotty should invoked 
by using the groff command with a -Tascii Or -Tlatin1 option. If no files are given, grotty will read the standard input. A 
filename of - will also cause grotty to read the standard input. O utput is written to the standard output. 

Normally, grotty prints a bold character c using the sequence 'c BACKSPACE c’ and an italic character c by the sequence 
'_BACKSPACE c'. T hese sequences can be displayed on a terminal by piping through u1(1). Pagers such as more(1) or 1ess(1) 
are also able to display these sequences. U se eather -8 or -u when pipinginto 1ess(1); use -» when piping into more(1). T here 
isno need to filter the output through co1(1) since grotty never outputs reverse line feeds. 

The font description file may contain a command: 

internalnamen 

wheren isa decimal integer. If the 01 bit inn is set, then thefont will be treated as an italic font; if the 02 bit is set, then it 


will be treated as a bold font. The code fidd in the font description field gives the code that will be used to output the 
character. T his code can also be used in the \n escape sequence in troff. 


OPTIONS 

-Fdir Search the directory dir /devname for font and device description files; name is the name of the device, usually ascii 
OF latin1. 

-h Use horizontal tabs in the output. T abs are assumed to be set every 8 columns. 

-f Use form feeds in the output. A form feed will be output at the end of each page that has no output on its last 
line 

-b Suppress the use of overstriking for bold characters. 

-u Suppress the use of underlining for italic characters. 

-B Use only overstriking for bold-italic characters. 

-U Use only undelining for bold-italic characters. 

-0 Suppress overstriking (other than for bold or underlined characters). 

-d Ignore all \D commands. W ithout this, grotty will render \p'1 ...' commands that have at least one zero 
argument (and so are either horizontal or vertical) using -, |, and + characters. 

-v Print the version number. 

FILES 

/usr/lib/groff/font/devascii/DESC Device description file for ascii device 

/usr/1ib/groff/font/devascii/F Font description file for font F of ascii device 

/usr/lib/groff/font/devlatini/DESc Device description file for 1atin1 device 

/usr/lib/groff/font/devlatin1/F Font description file for font F of 1atin1 device. 

/usr/lib/groff/tmac/tmac.tty M acrosfor use with grotty. 

/usr/lib/groff/tmac/tmac.tty-char Additional kludgy character definitions for use with grotty. 
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BUGS 
grotty is intended only for simple documents. 
There is no support for fractional horizontal or vertical motions. 
Thereis no support for \p commands other than horizontal and vertical lines. 
Characters above the first line (that is, with a vertical position of ) cannot be printed. 


SEE ALSO 


groff(1), gtroft(1), groff_out(5), groff_font(5), groff_char(7), u1(1), more(1), 1ess(1) 
Groff Vergon1.09, 14 February 1995 


gsoelim 

gsoelim— Interpret .so requests in groff input 
SYNOPSIS 

gsoelim [ -Cv ][files ... ] 
DESCRIPTION 


gsoelim readstiles and replaces lines of the form 


.sofile 


by the contents of file. It is useful if files included with so need to be preprocessed. N ormally, gsoe1im should be invoked 
with the -s option of groff. 


OPTIONS 
-C Recognize .so even when followed by a character other than space or newline 
-v Print the version number 

SEE ALSO 
groff(1) 


Groff Vergon1.09, 15 Seotember 1992 


gtbl 


gtbi— Format tables for trotf 


SYNOPSIS 


gtbl [ -Cv ][files ... ] 


DESCRIPTION 


This manual page describes the GN U version of tb1, which is part of the grotf document formatting systen. tb1 compiles 
descriptions of tables embedded within troff input files into commands that are understood by troff. Normally, it should 
be invoked using the -t option of groff. It is highly compatible with UNIX tb1. The output generated by GN U tb1 cannot 
be processed with UNIX troff; it must be processed with GN U troff. If no files are given on the command line, the 
standard input will be read. A filename of - will cause the standard input to be read. 
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OPTIONS 
-C Recognize .Ts and .tE even when followed by a character other than space or newline 
-v Print the version number 

USAGE 


Only the differences between GNU tb1 and UNIX tb1 are described here 


Normally, tb1 attempts to prevent undesirable breaks in the table by using diversions. T his can sometimes interact badly 
with macro packages’ own use of diversions, when footnotes, for example, are used. The nokeep option tals tb1 not to try to 
prevent breaks in this way. 


The decimalpoint option specifies the character to be recognized as the decimal point character in place of the default period. 
It takes an argument in parentheses, which must be a single character, as for the tab option. 


Thet format modifier can be followed by an arbitrary length font name in parentheses. 
There is ad format modifier that means that a vettically spanning entry should be aligned at the bottom of its range 


Thereisno limit on the number of columnsin a table, nor any limit on the number of text blocks. All the lines of atable are 
considered in deciding column widths, not just the first 200. T able continuation (.Ta) lines are not restricted to the first 200 
lines. 


Numeric and alphabetic itens may appear in the same column. 
Numeric and alphabetic itaens may span horizontally. 
tbl uses register, string, macro and diversion names beginning with 3. When using tb1, you should avoid using any names 
beginning with a 3. 
BUGS 


You should use .TSH/.TH in conjunction with a supporting macro package for all multipage boxed tables. If there isno header 
that you want to appear at the top of each page of the table, place the . TH line immediately after the format section. Do not 
enclose a multipage table within keep/rd ease macros, or divert it in any other way. 


A text block within a table must be able to fit on one page 
The bp request cannot be used to force a page break in a multipage table Instead, define sp as follows: 


.de BP 
-ie '\\n(.z" .bp \\$1 
-el \!.BP \\$1 


and use Bp instead of bp. 
SEE ALSO 
groff(1), gtroff(1) 
Groff Verson 1.09, 1 April 1993 


gtrotf 


gtroff— Format documents 


SYNOPSIS 


gtroff [-abivzCER] [-w name] [-W name] [-d cs] [-f fam] [-m name] [-n num] [-o list] [-r cn] [-T name] [-F dir] [-M 
dir] [nfiles...n] 


Part |: User Commands 


DESCRIPTION 


This manual page describes the GN U version of troff, which is part of the grott document formatting system. It is highly 
compatible with UNIX troff. Usually, it should be invoked using the groff command, which will also run preprocessors and 
postprocessors in the appropriate order and with the appropriate options. 


OPTIONS 


-dcs, -dname=s 
-ffam 

-mn ame 

-R 

-nnum 


-olist 


-rcn, -rname=n 
-Tname 
-Fdir 


-Mdir 


USAGE 


Generate an ASCII approximation of the typeset output. 


Print a backtrace with each warning or error message. T his backtrace should help track down the cause of 
the error. The line numbers given in the backtrace may not always correct: troff’s idea of line numbers 
gets confused by as or am requests. 


Read the standard input after all the named input files have been processed. 
Print the version number. 


Enable warning name. Available warnings are described in the “Warnings” subsection as follows. M ultiple 
-w options are allowed. 

Inhibit warning name. M ultiple -w options are allowed. 

Inhibit all error messages. 

Suppress formatted output. 

Enable compatibility mode 

Definec orname to beastrings;c must bea oneleater name 

Usefam as the default font family. 

Read in the file tmac.name. Normally, this will be searched for in /usr/lib/groff/tmac. 

Don't load troffre. 

Number the first page num. 

Output only pagesin |ist, which isa comma-separated list of page ranges; n means print pagen, m-n 


means print every page between m and n, -n means print every page up to n, n- means print every page 
from n. Troff will exit after printing the last page in the list. 


Se number register c or name ton; c must beaone-character name; n can be any troff numeric expression. 
Prepare output for device name, rather than the default ps. 


Search dir for subdirectories devname (name is the name of the device) for the pesc file and font files before 
the normal /usr/lib/groff/font. 


Search directory dir for macro files beforethe normal /usr/1ib/groff/tmac. 


Only the features not in UNIX trot are described here 


LONG NAMES 


The names of number registers, fonts, strings /macros/diversions, special characters can be of any length. In escape 
sequences, where you can use (xx for atwo-characte- name, you can use [xxx] for aname of arbitrary length: 


\ [Xxx] 
\F[XxXxX] 
\FLXXX] 


\n[Xxx ] 


Print the special character called xxx. 
Se font xxx. 

Interpolate string xxx. 

Interpolate number register xxx. 


FRACTIONAL POINT SIZES 
A scaled point is equal to 1/sizescale points, where sizescale is specified in the esc file (1 by default.) Thereis anew scale 
indicator z that has the effect of multiplying by sizescale. Requests and escape sequences in troff interpret arguments that 
represent a point size as being in units of scaled points, but they evaluate each such argument using a default scale indicator 
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of z. Arguments treated in this way are the argument to the ps request, the third argument to thecs request, the second and 
fourth arguments to the tkf request, the argument to the \H escape sequence, and those variants of the \s escape sequence 
that take a numeric expression as thar argument. 


For example, suppose sizescale is 1,000; then a scaled point will be equivalent to a millipoint; the request .ps 10.25 is 
equivalent to .ps 10.25z, and so sets the point size to 10,250 scaled points, which is equal to 10.25 points. 


Thenumber register \n(.s returns the point size in points as decimal fraction. T here is also anew number register \n[ .ps] 
that returns the point size in scaled points. 


It would make no sense to use the z scale indicator in a numeric expression whose default scale indicator was neither u nor z, 
and so troff disallows this. Similarly, it would make no sense to use a scaling indicator other than z or uin anumeric 
expression whose default scale indicator was z, and so troff disallows this as wal. 








There is also new scale indicator s that multiplies by the number of units in a scaled point. So, for example, \n[ .ps]s iS equal 
to 1m. Be sure not to confuse the s and z scale indicators. 


NUMERIC EXPRESSIONS 
Spaces are permitted in anumber expression within parentheses. 
m indicates a scale of hundredths of an em. 


e1>?e2 The maximum of e1 ande2. 
el<?e2 The minimum of e1 ande2. 
(ce) Evaluatee using as the default scaling indicator. If is missing, ignore scaling indicators in the evaluation 
of e. 
NEW ESCAPE SEQUENCES 
\A'anything' This expands to 1 or o according to whether anyt hing is or isnot acceptable as the name of a string, 


macro, diversion, number register, environment, or font. It will return o if anything isempty. This 
is useful if you want to look up user input in some sort of associative table 


\C xxx! Typeset character named xxx. N ormally itis more convenient to use \ [xxx]. But \c has the 
advantage that it is compatible with recent versions of UN IX and is available in compatibility 
mode 

\E This is equivalent to an escape character, but it’s not interpreted in copy mode. For example, 


strings to start and end superscripting could be defined like this: 
-ds { \v'-.3m'\s'\En[.s]*6u/1Qu' 
-ds { \s0\v'.3m' 


Theuse of \E ensures that these definitions will work even if \*F gets interpreted in copy-mode (for example, by being used 
in amacro argument). 


\N'n' T ypeset the character with coden in the current font. n can be any integer. M ost devices only have 
characters with codes between 0 and 255. If the current font does not contain a character with that 
code, special fonts will not be searched. T he \n escape sequence can be conveniently used on 
conjunction with the char request: 

.char \[phone] \f(ZDnN'37' 

The code of each character is given in the fourth column in the font description file after the 
charset Command. It is possible to include unnamed characters in the font description file by using 
aname of —; the \n escape sequence is the only way to use these 


\R'namen’ This has the same effect as .nrnamen 

\s(nn Se the point size to nn points; nn must be exactly two digits. 

\s[n], \s'n' Se the point size to n scaled points; n isanumeric expression with a default scale indicator of z. 
\Wx\ V(XX \VEXXX J Interpolate the contents of the environment variablexxx, as returned by getenv(3). \v is interpreted 


in copy-mode. 
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\YX\ YY (XX VY[XXX] 


\Z'anything' 


\$0 


\$* 
\$@ 


\$( on, \$[ nnn J 


\?anything\ ? 


\/ 


\, 


\# 


This is approximately equivalent to \x'\*[xxx ]'. H owever, the contents of the string or macro xxx 
are not interpreted; also, it is permitted for xxx to have been defined as a macro and thus contain 
newlines (it is not permitted for the argument to \x to contain newlines). The inclusion of newlines 
requires an extension to the UNIX troff output format and will confuse drivers that do not know 
about this extension. 


Print anything and then restore the horizontal and vertical position; anyt hing may not contain tabs 
or leaders. 


The name by which the current macro wasinvoked. The als request can make a macro have more 
than onename 


In amacro, the concatenation of all the arguments separated by spaces. 


In a macro, the concatenation of all the arguments with each surrounded by double quotes, and 
separated by spaces. 


In amacro, this gives the nnth or nnnth argument. M acros can havean unlimited number of 
arguments. 


W hen used in a diversion, this will transparently embed anything in thediversion. anything iSread 
in copy mode. W hen the diversion is reread, anyt hing will be interpreted. anyt hing may not contain 
newlines; use \! if you want to enbed newlinesin a diversion. The escape sequence \? is also 
recognized in copy mode and turned into a single internal code it is this code that terminates 
anything. Thus 

ne x 1 

ont 

.did 

V2\V2\VVV2VV AAV x\ VAP 2N2 

di 

nr x 2 

die 

.d 

di 

nr x 3 

.di f 

+e 

di 

“nr x 4 

f 


will print 4. 


This increases the width of the preceding character so that the spacing between that character and 
the following character will be correct if the following character is a Roman character. For example, 
if an italic f is immediately followed by aRoma right parenthesis, then in many fonts the top right 
portion of thef will overlap the top left of the right parenthesis, producing f), which is ugly. 
Inserting \/ produces and avoids this problem. It is a good idea to use this escape sequence 
wheever an italic character is immediately followed by aRoman character without any intervening 
space. 


This modifies the spacing of the following character so that the spacing between that character and 
the preceding character will correct if the preceding character is a Roman character. For example, 
inserting \, between the parenthesis and the f changes to (f. It isa good idea to use this escape 
sequence whenever a Roman character is immediately followed by an italic character without any 
intervening space. 


Like \& except that it behaves like a character declared with the cflags request to be transparent for 
the purposes of end-of-sentence recognition. 

This produces an unbreakable space that stretches like a normal interword space whe alineis 
adjusted. 

Everything up to and including the next newline is ignored. This is interpreted in copy mode. This 
is like \% except that \% does not ignore the terminating newline. 
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NEW REQUESTS 


.alnxx yy Create an aliasxx for number register object named yy. Thenew nameand theold namewill be 
exactly equivalent. If yy is undefined, a warning of type reg will be generated, and the request will 
be ignored. 

.alsxx yy Create an alias xx for request, string, macro, or diversion object named yy. Thenew nameand the 
old namewill be exactly equivalent (it is similar to a hard rather than a soft link). If yy isunde- 
fined, a warning of type mac will be generated, and the request will be ignored. Thede, am, di, da, 
ds, and as requests only create a new object if the name of the macro, diversion, or string diversion 
is currently undefined or if it is defined to be a request; normally, they modify the value of an 
existing object. 

-asciifyxx This request only existsin order to make it possible to make certain gross hacks work with GNU 
troff. It unformats the diversion xx in such a way that ASCII characters that were formatted and 
diverted into xx will be treated like ordinary input characters when xx isreread. For example this: 
.tr @. 

-di x 
@nr\n\1 
.br 

di 

.tr @@ 
-asciify x 
X 


will set register n to 1. 


.backtrace Print a backtrace of the input stack on stderr. 

. break Break out of awhile loop. See also the while and continue requests. Be sure not to confuse this with 
the br request. 

.cflagsncic2... Charactersci, ¢2, ... haveproperties determined by n, which is ored from the following. 

1 The character ends sentences. (Initially, characters .2! have this propety.) 

2 Linescan be broken before the character (initially, no characters have this property); a line will not 
be broken at a character with this property unless the characters on each side both have nonzero 
hyphenation codes. 

4 Lines can be broken after the character (initially, characters -\ (hy\ (em have this property); aline 
will not be broken at a character with this property unless the characters on each side both have 
nonzero hyphenation codes. 


8 The character overlaps horizontally (initially, characters \ (u1\(rn\ (ru have this propetty). 
16 The character overlaps vertically (initially, character \ (br has this property). 
32 An end-of-sentence character followed by any number of characters with this property will be 


treated as the end of asentence if followed by a newline or two spaces; in other words, the character 
is transparent for the purposes of end-of-sentence recognition; this is the same as having a zero 
space factor in T eX (initially, characters ') }*\ (dg\(rq have this property). 

.charcst ring D efine character to best ring. Every time character « needs to be printed, string will be processed 
in atemporary environment and the result will be wrapped up into asingle object. Compatibility 
mode will be turned off and the escape character will beset to \ whilestring is being processed. 
Any enboldening, constant spacing, or track kerning will be applied to this object rather than to 
individual characters in string. A character defined by this request can be used just likea normal 
character provided by the output device In particular, other characters can betranslated to it with 
the tr request; it can be made the leader character by the 1c request; repeated patterns can be drawn 
with the character by using the \1 and \L escape sequences, words containing the character can be 
hyphenated correctly, if the hcode request is used to give the character a hyphenation code. There is 
a special antirecursion feature U se of character within the character's definition will be handled 
like normal characters not defined with char. A character definition can be renoved with the rchar 
request. 
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» ChOpX x 


-closestream 


.continue 


.cpn 


- dOx xx 


. Famx x 


-fspecialfsis2 ... 


.ftrfg 


-heodectcodelc2code2.. 


-hlal ang 


-hlmn 


-hpffile 


hymn 


-hysn 


-kernn 


-msofile 


snrott 


-openstreamfil ename 


Chop the last character off macro, string, or diversion xx. Thisis useful for ranoving the newline 
from the end of diversions that are to be interpolated as strings. 

Close the stream named stream; stream will no longer bean acceptable argument to thewrite 
request. See the open request. 

Finish the current iteration of awhile loop. See also the while and break requests. 

If n isnonzero or missing, enable compatibility mode; otherwise, disable it. In compatibility mode, 
long names are not recognized, and the incompatibilities caused by long names do not arise 
Interpret. xxx with compatibility mode disabled. For example, .do fam T would have the same 
effect as .fam T except that it would work even if compatibility mode had been enabled. N ote that 
the previous compatibility mode is restored before any files sourced by xxx are interpreted. 

Sé@ the current font family to xx. The current font family is part of the current environment. See 
the description of the sty request for moreinformation on font families. 

When thecurrent font ist, fontss1, s2, ... will be special; that is, they will searched for 
characters not in the current font. Any fonts specified in the special request will be searched after 
fonts specified in the fspecial request. 

Translate font to 9. Whenever a font named is referred to in \f escape sequence, or in the ft, 
ul, bd, cs, tkf, special, fspecial, fp, or sty requests, font g will be used. If 9 is missing, or equal to 
f, then font f will not be translated. 

Se the hyphenation code of character c1 to code1 and that of 2 to code2. A hyphenation code must 
bea single input character (not a special character) other than a digit or a space. Initially, each 
lowercase letter has a hyphenation code, which isitsef, and each uppercase letter has a hyphenation 
code which is the lowercase version of its f. See also the hpf request. 

Sé@ the current hyphenation language to | ang. H yphenation exceptions specified with the hw 
request and hyphenation patterns specified with the hpf request are both associated with the 
current hyphenation language. T he hla request is usually invoked by the troffrc file 

Se the maximum number of consecutive hyphenated lines ton. If n is negative there is no 
maximum. T he default value is -1. T his value is associated with the current environment. Only 
lines output from an environment count towards the maximum associated with that environment. 
H yphens resulting from \% are counted; explicit hyphens are not. 

Read hyphenation patterns from fi! e; this will be searched for in the same way that tmac.name iS 
searched for when the -mname option is specified. It should have the same format as the argument to 
the \patterns primitive in T eX; the letters appearing in this file are interpreted as hyphenation 
codes. A % character in the patterns file introduces a comment that continues to the end of the line 
The set of hyphenation patterns is associated with the current language set by the hla request. The 
hpf request is usually invoked by the troffrc file 

Set the hyphenation margin ton: when the current adjustment mode is not b, the line will not be 
hyphenated if the lineis no more than n short. The default hyphenation margin is. The default 
scaling indicator for this request is m. The hyphenation margin is associated with the current 
environment. The current hyphenation margin is available in the \n{.hym] register. 

Se the hyphenation Space to n: when the current adjustment modeis b, don’t hyphenate the line if 
the line can be justified by adding no more than n extra space to each word space The default 
hyphenation space is @. The default scaling indicator for this request ism. The hyphenation space is 
associated with the current environment. The current hyphenation space is available in the 

\n[ .hys] register. 

If n isnonzero or missing, enable pairwise kerning; otherwise, disable it. 

The same as the so request except that fi | e is searched for in the same way that tmac.name iS 
searched for when the -mname option is specified. 

Make then built-in condition true and the t built-in condition false T his can be reversed using 
the troff request. 

Open filename for writing and associate the stream named stream with it. See also the close and 
write requests. 


-openastreamfilename 
-pnr 
-psocommand 


ptr 


srcharclc2... 


sPj, .rjn 


rnin xyy 


.shec 


.shiftn 


-Specialsis2... 
«Stynf 


-tkffsinis2n2 


-trffilename 


.trnt abcd 


Like open, but if filename exists, append to it instead of truncating it. 


Print the names and contents of all currently defined number registers on stderr. 


This behaves like the so request except that input comes from the standard output of command. 
Print the names and positions of all traps (not including input line traps and diversion traps) on 
stderr. Empty slotsin the page trap list are printed as wd, because they can affect the priority of 
subsequently planted traps. 

Remove the definitions of charactersc1, ¢2, ... Thisundoes theeffect of a char request. 

Right justify the next n input lines. Without an argument, right justify the next input line The 
number of lines to be right justified is available in the \nj .rj] register. This implicitly does .cea. 
The ce request implicitly does .rjo. 

Rename number register xx to yy. 

Se the soft hyphen character to c. If c isomitted, the soft hyphen character will be set to the 
default \ (hy. The soft hyphen character is the character that will be inserted when a word is 
hyphenated at a line break. If the soft hyphen character does not exist in the font of the character 
immediately preceding a potential break point, then the line will not be broken at that point. 

N either definitions (specified with the char request) nor translations (specified with the tr request) 
are considered when finding the soft hyphen character. 

In amacro, shift the arguments by n positions: argument i becomes argument i -n; arguments 1 to n 
will no longer be available. If n ismissing, arguments will be shifted by 1. Shifting by negative 
amounts is currently undefined. 

Fontssi,s2 are special and will be searched for characters not in the current font. 

Associate stylet with font position n. A font position can be associated either with a font or with a 
syle. The current font is the index of a font position and so is also athe a font ora style When it 
isastyle, the font that is actually used isthe font the name of which is the concatenation of the 
name of the current family and the name of the current style. For example, if the current font is 1 
and font position 1 is associated with styler and the current font family ist, then font tr will be 
used. If the current font is not a style, then the current family is ignored. W hen the requests cs, bd, 
tkf, uf, OF fspecial are applied to astyle, then they will instead be applied to the member of the 
current family corresponding to that style. T he default family can be set with the -F option. The 
styles Command in the pesc file controls which font positions (if any) are initially associated with 
styles rather than fonts. 

Enable track kerning for font. When the current font ist , the width of every character will be 
increased by an amount between n1 and 2; when thecurrent point size is less than or equal to s1, 
the width will be increased by n1; when it is greater than or equal to s2, the width will be increased 
by n2; when the point size is greater than or equal to s1 and less than or equal to s2, the increase in 
width is alinear function of the point size 

Transparently output the contents of filet i! ename. Each line is output as it would be were it 
preceded by \!; however, the lines are not subject to copy-mode interpretation. If the file does not 
end with a newline, then a newline will be added. For example, you can define a macro x 
containing the contents of filer, using 

-dix 

strft 

di 


Unlike with the ct request, the file cannot contain characters such as nut that are not legal troff 
input characters. 

This is the same as the tr request except that the translations do not apply to text that is transpar- 
ently throughput into a diversion with \!. For example, 

-tr ab 

.di x 

\!.tma 
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.trott 


.vptn 


»warnn 


-whilecanyt hing 


-writestreamanything 


EXTENDED REQUESTS 


.cffilename 


»OVXX 


Fpn ff 2 


»ssmn 


-tanin2...nnTrir2...rn 


di 


will print b; if trnt is used instead of tr, it will print a. 


M ake then built-in condition false, and the ¢ built-in condition true. T his undoes the effect of the 
nroff request. 


Enable vertical position trapsifn isnonzero, disable them otherwise. Vertical position traps are 
traps set by the wh or at requests. T raps set by the it request are not vertical position traps. The 
parameter that controls whether vertical position traps are enabled is global. Initially, vertical 
position traps are enabled. 


Control warnings. n is the sum of the numbers associated with each warning that isto be enabled; 
all other warnings will be disabled. The number associated with each warning is listed in the 
“Warnings” subsection. For example, .warn o will disable all warnings, and .warn 1 will disable all 
warnings except that about missing characters. If n is not given, all warnings will be enabled. 


While condition c is true, accept anyt hing aSinput; ¢ can be any condition acceptable to an if 
request; anything can comprise multiple lines if the first line starts with \_ and the last line ends 
with \}. See also the break and continue requests. 


Write anything to the stream named stream. stream must previously have bem the subject of an 
open request. anything is read in copy mode a leading will be stripped. 


W hen used in a diversion, this will enbed in thediversion an object which, when reread, will cause 
the contents of fi | ename to be transparently copied through to the output. In UNIX troff, the 
contents of fi! ename are immediately copied through to the output regardless of whether there isa 
current diversion; this behavior is so anomalous that it must be considered a bug. 


If xx isnot anumbe,, this will switch to anamed environment called xx. The environment should 
be popped with a matching ev request without any arguments, just as for numbered environments. 
Theeisno limit on the number of named environments; they will be created the first time that 
they are referenced. 


T he fp request has an optional third argument. T his argument gives the external name of the font, 
which is used for finding the font description file The second argument gives the internal name of 
the font, which is used to refer to the font in trot after it has been mounted. If there is no third 
argument, then the internal name will be used as the external name. T his feature allows you to use 
fonts with long names in compatibility mode 


W hen two arguments are given to the ss request, the second argument gives the sentence space size. 
If the second argument is not given, the sentence space size will be the same as the word space size. 
Like the word spacesize the smtence spaceisin units of one twelfth of the spacewidth parameter 
for the current font. Initially, both the word space size and the sentence space size are 12. The 
sentence space size is used in two circumstances: If the end of a sentence occurs at the end of aline 
in fill mode, then both an interword space and a sentence space will be added; if two spaces follow 
the end of a sentence in the middle of aline, then the second space will be a sentence space. N ote 
that the behavior of UN IX troff will be exactly that exhibited by GN U troff if asecond argument 
is never given to the ss request. In GNU troff, asin UNIX troff, you should always follow a 
sentence with either a newline or two spaces. 


Set tabs at positionsn1, n2,...,nn and then set tabs at nn+r1, nn+r2,...., nn+rn and then at 


nn¢rntr1, nn4rntr2,..., nntrn4rn, and So on. For example .ta T .5i will set tabs every half an 
inch. 


\n[. 
\n[. 


\n[ 


\n[ 
\n[ 
\n[ 
\n[ 
\n[ 
\n[ 
\n[ 
\n[ 


\n[ 


\n[ 
\n[ 


\n[ 
\n[ 
\n 


\n[ 
\n 
\n 
\n[ 


\n( 
\n( 


9] 
\n[. 
\n[. 
\n[. 
\n[. 
-hym] 
-hys] 


.in 


.pn 


ps 
-psr] 
\n[. 
“sr 
.tabs] 


am] 


p] 


hla] 
hlc] 
hlm] 





-kern] 
.lg 
11 
alt 


ne 


rj 





-trunc] 


.SS] 
.SSs] 
-vpt] 


-warn] 


-X 


y 


gtroff 
The current font family. This is a string-valued register. 
Thenumber of the next free font position. 
Always 1. M acros should use this to determine whether they are running unde GN U troff. 
The current hyphenation language as set by the hia request. 
The number of immediately preceding consecutive hyphenated lines. 
The maximum alowed number of consecutive hyphenated lines, as set by the him request. 
The current hyphenation flags (as set by the hy request.) 
The current hyphenation margin (as set by the hym request.) 
Thecurrent hyphenation space (as set by the hys request.) 
The indent that applies to the current output line. 
1 if pairwise kerning is enabled, o otherwise. 
Thecurrent ligature mode (as set by the 1g request.) 
Theline length that applies to the current output line 
The title length as set by the 1t request. 


The amount of space that was needed in the last ne request that caused a trap to be sprung. U seful in 
conjunction with the \n[.trunc] register. 


Thenumber of the next page either the value set by a pn request, or thenumber of the current page 
plus 1. 

Thecurrent pointsizein scaled points. 

Thelast requested pointsize in scaled points. 

The number of lines to be right-justified as se by the rj request. 

The last requested pointsize in points as a decimal fraction. This is a string-valued register. 

A string representation of the current tab settings suitable for use as an argument to the ta request. 

The amount of vertical space truncated by the most recently sprung vertical position trap, or, if the trap 
was sprung by an ne request, minus the amount of vertical motion produced by the ne request. In other 
words, at the point a trap is sprung, it reoresents the difference of what the vertical position would have 
been but for the trap, and what the vertical position actually is. U seful in conjunction with the \n[.ne] 
register. 

T hese give the values of the parameters set by the first and second arguments of the ss request. 





1 if vertical position traps are enabled, o otherwise 


The sum of the numbers associated with each of the currently enabled warnings. T he number associated 
with each warning is listed in the “Warnings” subsection. 


The major version number. For example, if the version number is 1.03 then \n(.x will contain 1. 
The minor version number. For example, if the version number is 1.03 then \n(.y will contain 03. 
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The following registers are set by the \w escape sequence: 


\n[rst] 

\n[rsb Likethe st and sb registers, but takes account of the haghts and depths of characters. 

\n[ssc The amount of horizontal space (possibly negative) that should be added to the last character before a 
subscript. 

\n[ skw H ow far to right of the center of the last character in the \w argument, the center of an accent from a 


roman font should be placed over that character. 


The following read/write number registers are available: 


\n[systat] The return value of the system() function executed by the last sy request. 

\n[slimit] If greater than 0, the maximum number of objects on the input stack. If less than or equal to 0, there isno 
limit on the number of objects on the input stack. W ith no limit, recursion can continue until virtual 
memory is exhausted. 





MISCELLANEOUS 
Fonts not listed in the esc file are automatically mounted on the next available font position when they are referenced. 
If afont is to be mounted explicitly with the fp request on an unused font position, it should be mounted on the first unused 
font position, which can be found in the \n[.fp] register; although trot does not enforce this strictly, it will not allow a font 
to be mounted at a position whosenumber is much greater than that of any currently used position. 


Interpolating a string does not hide existing macro arguments. Thusin amacro, a more efficient way of doing 
-xx\\$@ 

is 

\\*[xx]\\ 


If the font description file contains pairwise kerning information, characters from that font will be kerned. K ening between 
two characters can be inhibited by placing a\a between them. 


In a string comparison in a condition, characters that appear at different input levels to the first delimiter character will not 
be recognized asthesecond or third delimiters. This applies also to the t1 request. In a \w escape sequence, a character that 
appears at a different input levd to the starting delimiter character will not be recognized as the closing delimiter character. 
W hen decoding a macro argument that is delimited by double quotes, a character that appears at a different input level to 
the starting delimiter character will not be recognized as the closing ddimiter character. The implementation of \$@ ensures 
that the double quotes surrounding an argument will appear the same input level, which will be different to the input level 
of the argument itself. In along escape name j will not be recognized as a closing ddimiter except when it occurs at the same 
input level as the opening }. In compatibility mode no attention is paid to the input leva. 





T herve are some new types of condition: 
.ifrxxx Trueif thereis anumber register named xxx. 
.ifdxxx  Trueif thereis a string, macro, diversion, or request named xxx. 


.ifech Trueif thereis a character ch available; ch is@ther an ASCII character or a special character \(xx or \ [xxx]; the 
condition will also be true if ch has been defined by the char request. 


WARNINGS 
The warnings that can be given by troft are divided into the following categories. The name associated with each warning is 
used by the -w and -w options; the number is used by the warn request, and by the .warn register. 


chart N onexistent characters. T hisis enabled by default. 
number2 Invalid numeric expressions. T his is enabled by default. 
break4 In fill mode, lines which could not be broken so that their length was less than the line length. T hisis 


enabled by default. 
delims Missing or mismatched closing delimiters. 


gtroff 247 


e116 Use of the e1 request with no matching ie request. 

scale32 M eaningless scaling indicators. 

range64 Out of range arguments. 

syntax128 D ubious syntax in numeric expressions. 

di256 Use of di or da without an argument when there isno current diversion. 

mac512 Use of undefined strings, macros, and diversions. When an undefined string, macro, or diversion is used, 
that string is automatically defined as empty. So, in most cases, at most one warning will be given for each 
name 

reg1024 Use of undefined number registers. When an undefined number register is used, that register is automati- 


cally defined to havea value of @. A definition is automatically made with a value of 0. So, in most cases, at 
most onewarning will be given for use of a particular name. 


tab2048 Inappropriate use of atab character. Either use of a tab character where a number was expected, or use of 
tab character in an unquoted macro argument. 


right-brace4o96 Useof \g whereanumber was expected. 


missing8192 Requests that are missing nonoptional arguments. 

input 16384 Illegal input characters. 

escape32768 Unrecognized escape sequences. W hen an unrecognized escape sequence is encountered, the escape 
character is ignored. 

space65536 M issing space between a request or macro and its argument. T his warning will be given when an 


undefined name longer than two characters is encountered, and the first two characters of the name make 
a defined name The request or macro will not be invoked. When this warning is given, no macro is 
automatically defined. T hisis enabled by default. T his warning will never occur in compatibility mode. 
font131072 N onexistent fonts. This is enabled by default. 
ig262144 Illegal escapes in text ignored with the ig request. T hese are conditions that are errors when they do not 
occur in ignored text. 


T hee are also names that can be used to refer to groups of warnings: 


all All warnings except di, mac, and reg. It is intended that this covers all warnings that are useful with 
traditional macro packages. 
w All warnings. 
INCOMPATIBILITIES 
Long names cause some incompatibilities UNIX trof¢# will interpret 
.dsabed 


as defining a string ab with contents ca. Normally, GNU troff will interpret this as a call of amacro named dsabca. Also 
UNIX trof# will interpret \*[ or \n[ as references to a string or number register called [. In GNU troff, howeve,, this will 
normally be interpreted as the start of along name In compatibility ModeGN U trof¢ will interpret these things in the 
traditional way. In compatibility mode however, long names are not recognized. C ompatibility mode can be turned on with 
the -c command-line option, and turned on or off with the cp request. The number register \n(.c is if compatibility mode 
ison, @ otherwise. 


GNU troff does not allow the use of the escape sequences in names of strings, macros, diversions, number registers, fonts, or 
environments; UNIX troff does. The \a escape sequence may be helpful in avoiding use of these escape sequences in names. 


Fractional point sizes cause one noteworthy incompatibility. In UNIX troff the ps request ignores scale indicators and so 
«ps 1Qu 


will set the pointsize to 10 points, whereas in GN U troff it will set the pointsize to 10 scaled points. 
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In GNU troft there is a fundamental difference between unformatted, input characters, and formatted, output characters. 
Everything that affects how an output character will be output is stored with the character; after an output character has been 
constructed, it is unaffected by any subsequent requests that are executed, including ba, cs, tkf, tr, Or fp requests. N ormally 
output characters are constructed from input characters at the moment immediately before the character is added to the 
current output line. M acros, diversions, and strings are all, in fact, the same type of object; they contain lists of input 
characters and output characters in any combination. An output character does not behave like an input character for the 
purposes of macro processing; it does not inherit any of the special properties that the input character from which it was 
constructed might have had. For example this: 

-di x 

VA 

.br 


di 
X 


will print \\ in GNU trof#; each pair of input \sisturned into one output \ and the resulting output \s are not interpreted 
as escape characters when they are reread. UN 1X troff would interpret them as escape characters when they were reread and 
would end up printing one \. T he correct way to obtain a printable \ isto use the \e escape sequence: this will always print a 
single instance of the current escape character, regardless of whether or not it is used in adiversion; it will also work in both 
GNU troff and UNIX trof¢. If you wish for some reason to store in a diversion an escape sequence that will be interpreted 
when thediversion is reread, you can ether use the traditional \: transparent output facility, or, if thisis unsuitable, thenew 
\? escape sequence. 


ENVIRONMENT 
GROFF_TMAC_PATH A colon-separated list of directories in which to search for macro files. 
GROFF_TYPESETTER D efault device 


GROFF_FONT_PATH A colon-separated list of directories in which to search for the devname directory. troff will search 
in directories given in the -F option before these, and in standard directories (:/usr/1ib/groff/font, 
:/usr/lib/font, and :/usr/lib/font) after these. 


FILES 
/usr/lib/groff/font/devname/DESC 
/usr/lib/groff/tmac/troffre Initialization file 
/usr/1ib/groff/tmac/tmac.name M acro files 
/usr/1ib/groff/font/devname /DESC D evice description file for device name 
/usr/lib/groff/font/devname/F Font file for font F of devicename 


SEE ALSO 


groff(1) gtb1(1), gpic(1), geqn(1), grops(1), grodvi(1), grotty(1), groff_font(5), groff_out(5), groff_char(7) 
Groff Verson 1.09, 14 February 1994 


Z1p, guNZ1p, ZCatgzip, gunzip, zcat 


gzip, gunzip, zcatgzip, gunzip, zeat— Compress or expand files 


SYNOPSIS 
gzip [ -acdfhlLnNrtvV19 ][-Ssuffix] [ name ... ] 
gunzip [ -acfhlLnNrtvV ][-Ssuffix] [ name ... ] 


zceat [ -fhLV ][name ... ] 


gzip, gunzip, zcatgzip, gunzip, zcat 
DESCRIPTION 


gzip reduces the size of the named files using Lempd-Ziv coding (LZ 77). W henever possible, each file is replaced by one 
with the extension .gz, while keeping the same ownership modes, access, and modification times. (T he default extension is 
-gz for VMS, z for MS-DOS, OS/2 FAT, Windows NT FAT and Atari.) If no files are specified, or if afilename is -, the 
standard input is compressed to the standard output. gzip will only attempt to compress regular files. In particular, it will 
ignore symbolic links. 


If the compressed filename is too long for its filesystem, gzip truncates it. gzip attempts to truncate only the parts of the 
filename longer than three characters. (A part is ddimited by dots.) If the name consists of small parts only, the longest parts 
are truncated. For example, if filenames are limited to 14 characters, gzip.msdos.exe is compressed to gzi.msd.exe.gz. N ames 
are not truncated on systems that do not have a limit on filename length. 


By default, gzip keeps the original filename and timestamp in the compressed file T hese are used when decompressing the 
file with the -n option. T his is useful when the compressed filename was truncated or when the time stamp was not preserved 
after a file transfer. 


Compressed files can be restored to their original form using gzip -d Or gunzip or zcat. If the original name saved in the 
compressed file is not suitable for its filesystem, a new name is constructed from the original one to make it legal. 


gunzip takes a list of files on its command line and replaces each file whose name ends with .gz, -gz, .z, -z, z, of .z and which 
begins with the correct magic number with an uncompressed file without the original extension. gunzip also recognizes the 
special extensions .tgz and .taz asshorthands for .tar.gz and .tar.z respective y. W hen compressing, gzip uses the . tgz 
extension if necessary instead of truncating a file with a .tar extension. 


gunzip can currently decompress files created by gzip, zip, compress, compress -H, Of pack. The detection of the input format 
is automatic. When using the first two formats, gunzip checks a 32-bit CRC. For pack, gunzip checks the uncompressed 
length. The standard compress format was not designed to allow consistency checks. H oweve’, gunzip is sometimes able to 
detect a bad .z file If you get an error when uncompressing a .z file do not assume that the .z file is correct simply because 
the standard uncompress does not complain. T his generally means that the standard uncompress does not check its input, and 
happily generates garbage output. TheSCO compress -H format (1zh compression method) does not includea CRC but also 
allows some consistency checks. 


Files created by zip can be uncompressed by gzip only if they havea single manber compressed with the deflation method. 
This feature is only intended to hap conversion of tar. zip files to the tar.gz format. To extract zip files with several 
members, use unzip instead of gunzip. 


zeat iSidentical to gunzip -c. (On some systems, zcat may be installed as gzcat to preserve the original link to compress.) 
zcat uncompresses dither a list of files on the command line or its standard input and writes the uncompressed data on 
standard output. zcat will uncompress files that have the correct magic number whether they have a . gz suffix or not. 


gzip uses the Lempa-Ziv algorithm used in zip and pkzip. The amount of compression obtained depends on the size of the 
input and the distribution of common substrings. T ypically, text such as source code or English is reduced by 60 to 70 
percent. Compression is generally much better than that achieved by LZW (as used in compress), H uffman coding (as used 
in pack), or adaptiveH uffman coding (compact). 


Compression is always performed, even if the compressed file is slightly larger than the original. T he worst case expansion isa 
few bytes for the gzip file header, plus 5 bytes every 32K B block, or an expansion ratio of 0.015 percent for large files. N ote 
that the actual number of used disk blocks almost never increases. gzip preserves the mode, ownership, and timestamps of 
files when compressing or decompressing. 


OPTIONS 


-a -ascii ASCII text mode convert end-of-lines using local conventions. T his option is supported 
only on some non-UN IX systems. For MS-DOS, cr LF is converted to LF when compress- 
ing, and LF is converted to ck LF when decompressing. 

-c -stdout -to-stdout W rite output on standard output; keep original files unchanged. If there are several input 
files, the output consists of a sequence of independently compressed members. T 0 obtain 
better compression, concatenate all input files before compressing them. 
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-d 
-f 


-h 
-1 


role 


-n 


-N 


-q 
=f 


-S 


-t 


-V 


-V 
-# 


-decompress -uncompress 


-force 


-help 
-list 


-license 


-no-name 


-name 


-quiet 


-recursive 


.suf -suffix 


-test 


-verbose 


-version 
-fast -best 


suf 


D ecompress. 

Force compression or decompression even if the file has multiple links or the corresponding 
file already exists, or if the compressed data is read from or written to a terminal. If the 
input data is notin a format recognized by gzip, and if the option -stdout is also given, 
copy theinput data without change to the standard output; let zcat behaveas cat. If -f is 
not given, and when not running in the background, gzip prompts to verify whether an 
existing file should be overwritten. 

Display a help screen and quit. 

For each compressed file, list the following fields: compressed size (size of the compressed 
file), uncompressed size (size of the uncompressed file), ratio (compression ratio— 0.0% if 
unknown), uncompressed name (name of the uncompressed file). The uncompressed size is 
given as -1 for files not in gzip format, such as compressed .z files. To get the uncompressed 
size for such afile, you can use: 

zcat file.Z | we -c 

In combination with the -verbose option, the following fidds are also displayed: method 
(compression method), crc (the 32-bit CRC of the uncompressed data), date & time 
(timestamp for the uncompressed file). The compression methods currently supported are 
deflate, compress, 1zh (SCO compress -H) and pack. The crc iS given as frffttft for afile 
not in gzip format. 

With -name, the uncompressed name, date and time are those stored within the compressed 
file if present. 

With -verbose, the size totals and compression ratio for all files is also displayed, unless 
some sizes are unknown. W ith -quiet, the title and totals lines are not displayed. 

Display the gzip license and quit. 

W hen compressing, do not save the original filename and timestamp by default. (The 
original name is always saved if the name had to be truncated.) W hen decompressing, do 
not restore the original filename if present (remove only the gzip suffix from the compressed 
filename) and do not restore the original timestamp if present (copy it from the compressed 
file). This option is the default when decompressing. 

When compressing, always save the original filename and timestamp; this is the default. 

W hen decompressing, restore the original fileaame and timestamp if present. T his option is 
useful on systems that have alimit on filename length or when the timestamp has been lost 
after a file transfer. 

Suppress all warnings. 

Travd the directory structure recursively. If any of the filenames specified on the command 
line are directories, gzip will descend into the directory and compress all the files it finds 
there (or decompress them in the case of gunzip). 

Use suffix .suf instead of .gz. Any suffix can be given, but suffixes other than .z and .gz 
should be avoided to avoid confusion when files are transferred to other systems. A null 
suffix forces gunzip to try decompression on dll given files regardless of suffix, asin the 
following: 

gunzip -s "* * (*.* forMS-DOS) 

Previous versions of gzip used the .z suffix. This was changed to avoid a conflict with 
pack(1). 

Test. Check the compressed file integrity. 

Verbose. Display thenameand percentage reduction for each file compressed or decom- 
pressed. 

Version. Display the version number and compilation options, then quit. 

Regulate the speed of compression using the specified digit #, where -1 or --fast indicates 
the fastest compression method (less compression) and -9 or - -best indicates the slowest 
compression method (best compression). T he default compression leva is -6 (that is, biased 
towards high compression at expense of speed). 


gzip, gunzip, zcatgzip, gunzip, zcat [= | 
ADVANCED USAGE 


M ultiple compressed files can be concatenated. In this case, gunzip will extract all members at once For example, 
gzip -c file1 >foo.gz gzip -c file2>>> foo.gz 

Then 

gunzip -c foo 

is equivalent to 

cat file1 file2 


In case of damage to one member of a .gz file, other members can still be recovered (if the damaged member is removed). 
H owever, you can get better compression by compressing all members at once. 


cat file! file2 | gzip > foo.gz 

compresses better than 

gzip -c file1 file2 >foo.gz 

If you want to recompress concatenated files to get better compression, use 
gzip -cd old.gz | gzip > new.gz 


If a compressed file consists of several members, the uncompressed size and CRC reported by the-1ist option applies to the 
last member only. If you need the uncompressed size for all members, you can use 


gzip -cd file.gz | we -c 

If you wish to create a single archive file with multiple members so that members can later be extracted independently, use an 
archiver such as tar Or zip. GNU tar supports the -z option to invoke gzip transparently. gzip is designed as a complement 
to tar, not asa replacenent. 


ENVIRONMENT 


The environment variable ezrp can hold a set of default options for gzip. T hese options are interpreted first and can be 
overwritten by explicit command-line parameters. For example 


For sh: GZIP="-8v -name" 
Export ezrp for csh: setenv GZIP "-8v -name" 
For MS-DOS: set GZIP=-8v -name 


On Vax/VMS, the name of the environment variable is z1p_opt, to avoid a conflict with the symbol set for invocation of the 
program. 


SEE ALSO 


znew(1), zemp(1), zmore(1), zforce(1), gzexe(1), zip(1), unzip(1), compress(1), pack(1), compact(1) 


DIAGNOSTICS 
Exit status isnormally 0; if an error occurs, exit status is 1. If a warning occurs, exit status is 2. 
Usage gzip [-cdfhlLnNrtvV19] [-S suffix] [file ...] 
Invalid options were specified on the command line. 
file: not in gzip format 
The file specified to gunzip has not been compressed. 
file: Corrupt input. Use zcat to recover some data. 
The compressed file has been damaged. T he data up to the point of failure can be recovered using 


zcat file > recover 
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ile: compressed with xx bits, can only handle yy bits 


e was compressed (using LZW) by a program that could deal with more bits than the decompress code on this machine 
Recompress the file with gzip, which compresses better and uses less memory. 


e: already has .gz suffix--no change 


HB 


HB 


The file is assumed to be already compressed. Rename the file and try again. 


e already exists; do you wish to overwrite (y or n)? 








HB 


Respond y if you want the output file to be replaced; n if not. 

gunzip: corrupt input 

A SIGSEGV violation was detected, which usually means that the input file has been corrupted. 

XX. X% 

Percentage of the input saved by compression. (Relevant only for -v and -I.) 

- not a regular file or directory: ignored 

When the input fileis not a regular file or directory, (such as a symbolic link, socket, FIFO, device file), it is left unaltered. 
- has xx other links: unchanged 

The input file has links; it is left unchanged. See In(1) for more information. 

Use the -¢ flag to force compression of files that are multiply linked. 


CAVEATS 


W hen writing compressed data to a tape it is generally necessary to pad the output with zeroes up to a block boundary. 
When the data is read and the whole block is passed to gunzip for decompression, gunzip detects that there is extra trailing 
garbage after the compressed data and emits a warning by default. You have to use the -quiet option to suppress the 
warning. T his option can be set in the gzip environment variable asin the following: 


for sh: GZIP="-q" tar -xfz -block-compress /dev/rst® for csh: 
(setenv GZIP -q; tar -xfz -block-compr /dev/rstO 


In the preceding example, gzip isinvoked implicitly by the -z option of GNU tar. M ake sure that the same block size (-b 
option of tar) is used for reading and writing compressed data on tapes. (T his example assumes you are using the GN U 
version of tar.) 


BUGS 


The -1ist option reports incorrect sizes if they exceed two gigabytes. The -1ist option reports sizes as -1 and cre aS ffffffff 
if the compressed file ison a nonseekable media. 


In some rare cases, the -best option gives worse compression than the default compression leva (-6). On some highly 
redundant files, compress compresses better than gzip. 


Local 


gzexe 


gzexe— Compress executable files in place 


SYNOPSIS 


gzexe [ name ... ] 


~ 
DESCRIPTION 


The gzexe utility enables you to compress executables in place and have them automatically uncompress and execute when 
you run then (at a penalty in performance). For example if you execute gzexe /bin/cat, it will create the following two files: 


-r-xr-xr-x 1 root bin 9644 Feb 11 11:16 /bin/cat 
-r-xr-xr-x 1 bin bin 24576 Nov 23 13:21 /bin/cat™ 


/bin/cat~ isthe original file and /bin/cat is the sdf-uncompressing executable file You can remove /bin/cat” when you are 
sure that /bin/cat works properly. 


This utility is most useful on systems with very small disks. 


OPTIONS 

-d D ecompress the given executables instead of compressing then 
SEE ALSO 

gzip(1), znew(1), zmore(1), zemp(1), zforce(1) 
CAVEATS 


The compressed executable is a shell script. This may create some security holes. In particular, the compressed executable 
relies on the PATH environment variable to find gzip and some other utilities (tail, chmod, 1n, sleep). 


BUGS 


gzexe attempts to retain the original file attributes on the compressed executable, but you may have to fix than manually in 
some Cases, usINg chmod OF chown. 


head 


head— O utput the first part of files 
SYNOPSIS 


head [-c N[bkm]] [-n N] [-qv] [--bytes=N[bkm]] [--lines=N] [--quiet] [--silent] 
[--verbose] [--help] [--version] [file...] 


head [-Nbcklmqv] [file...] 


DESCRIPTION 


This manual page documents the GN U version of head. head prints the first part (10 lines by default) of each given file it 
reads from standard input if no files are given or when afilename of - is encountered. If morethan onefileis given, it prints 
a header consisting of the file's name enclosed in ==> and <== before the output for each file 


OPTIONS 


head accepts two option formats: the new one in which number's are arguments to the option letters; and the old one in 
which the number precedes any option letters. 


-c N, --bytes N Print first n bytes. v isanonzero integer, optionally followed by one of the following characters to 
specify a different unit. 
b 512-byte blocks. 
k 1-kilobyte blocks. 
m 1-megabyte blocks. 
-1, -n N, --lines N Print first n lines. 
-q, --quiet, --silent N ever print filename headers. 
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-v, --verbose 


Always print filename headers. 


--help Print a usage message and exit with anonzero status. 
--version Print version information on standard output, then exit. 
GNU Tet Utilitie 

hexdump 

hexdump— ASCII, decimal, hexadecimal, octal dump 
SYNOPSIS 

hexdump [-bcdovx] [-e format_string] [-f format_file] [-n length] [-s skip] [file ...] 
DESCRIPTION 

The hexdump utility is a filter that displays the specified files, or the standard input, if no files are specified, in a user-specified 

format. 


The options are as follows: 


-b 


-S 


format_string 


format_file 


length 


offset 


Onebyte octal display. Display the input offset in hexadecimal, followed by sixteen space 
separated, three-column, zero-filled bytes of input data, in octal, pe line 

Onebyte character display. Display the input offset in hexadecimal, followed by sixteen space 
separated, three-column, space-filled, characters of input data per line 

Two-byte decimal display. Display the input offset in hexadecimal, followed by aght space 
separated, five-column, zero-filled, two-byte units of input data, in unsigned decimal, per line 
Specify a format string to be used for displaying data. 

Specify a file that contains one or more newline separated format strings. Empty lines and lines 
whose first nonblank character is a hash mark (#) are ignored. 

Interpret only length bytes of input. 

Two-byte octal display. Display the input offset in hexadecimal, followed by eight space-separated, 
six-column, zero-filled, two-byte quantities of input data, in octal, per line 

Skip offset bytes from the beginning of the input. By default, offset isinterpreted as a decimal 
number. W ith a leading ox or ex, offset isinterpreted asa hexadecimal numbe;; otherwise, with a 
leading 0, offset isinterpreted as an octal number. Appending the character b, k, or m to offset 
causes it to be interpreted asa multiple of 512, 1024, or 1048576, respectively. 

The -v option causes hexdump to display all input data. Without the -v option, any number of 
groups of output lines, which would be identical to the immediately preceding group of output 
lines (except for the input offsets), are replaced with a line comprised of a single asterisk. 

T wo-byte hexadecimal display. D isplay the input offset in hexadecimal, followed by eight, space 
separated, four-column, zero-filled, two-byte quantities of input data, in hexadecimal, per line 


For each input file, hexdump sequentially copies the input to standard output, transforming the data according to the format 
strings specified by the -e and -¢ options, in the order that they were specified. 
FORMATS 


A format string contains any number of format units, separated by whitespace A format unit contains up to three items: an 
iteration count, a byte count, and a format. 


T he iteration count is an optional positive integer, which defaults to one Each format is applied iteration count times. 


The byte count is an optional positive integer. If specified, it defines the number of bytes to be interpreted by each iteration 
of the format. 


hexdump [= | 


If an iteration count and/or a byte count is specified, a single slash must be placed after the iteration count and/or before the 
byte count to disambiguate then. Any whitespace before or after the slash is ignored. 


The format is required and must be surrounded by double quote (“ ”) marks. It is interpreted as an fprintf-style format 
string (see fprintt(3)) with the following exceptions: 


m An asterisk (*) may not be used as afield width or precision. 

m A bytecount or field precision is required for each s conversion character (unlike the fprintt(3) default, which prints 
the entire string if the precision is unspecified). 

m Theconversion characters h, 1, n, p, and q arenot supported. 

m Thesinglecharacter escape sequences described in theC standard are supported: 


NUL \o 
Alert character \a 
Backspace \b 
Form-feed \f 
Newline \n 
Carriage return \r 
Tab \t 
Vertical tab \v 


hexdump also supports the following additional conversion strings: 


a[dox] Display the input offset, cumulative across input files, of the next byte to be displayed. T he appended characters 
d, o, and x specify the display base as decimal, octal, or hexadecimal respectively. 


A[dox] Identical to the a conversion string except that it is only performed once, when all of the input data has been 
processed. 
c Output charactersin the default character set. N onprinting characters are displayed in three-character, zero- 


padded octal, except for those representable by standard escape notation (see preceding list), which are displayed 
as two-character strings. 


p Output charactersin the default character set. N onprinting characters are displayed as a single period. 
u Output U.S. ASCII characters, with the exception that control characters are displayed using the lowercase names 
in the following mini-table. Characters greater than oxft, hexadecimal, are displayed as hexadecimal strings. 
000 nul 001 soh 002 stx 003 etx 004 eot 005 eng 
006 ack 007 bel 008 bs 009 ht Q0A If 0B vt 
o0c ff 00D cr QE so OF si 010 dle 011 det 
012 dc2 013 dc3 014 dc4 015 nak Q@16 syn 017 etb 
018 can 019 em 1A sub 1B esc @1C fs @1D gs 
O1E rs O1F us OFF del 


The default and supported byte counts for the conversion characters are as follows: 


%_C,%_P, %_U, %C Onebyte counts only. 
%d, %i, %0, %U, %X, %X Four-byte default; one, two-, and four-byte counts supported. 
%E, %e, %F, %G, %Q Eight-byte default, four-byte counts supported. 


The amount of data interpreted by each format string is the sum of the data required by each format unit, which is the 
iteration count times the byte count, or the iteration count timesthe number of bytes required by the format if the byte 
count is not specified. 


The input is manipulated in blocks; a block is defined as the largest amount of data specified by any format string. Format 
strings interpreting less than an input block's worth of data, whose last format unit both interprets some number of bytes 
and does not have a specified iteration count, have the iteration count incremented until the entire input block has been 
processed or there is not enough data renaining in the block to satisfy the format string. 
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If, ather as a result of user specification or hexdump modifying the iteration count as described, an iteration count is greater 
than one, no trailing whitespace characters are output during the last iteration. 


It isan error to specify a byte count as well as multiple conversion characters or strings unless all but one of the conversion 
characters or stringsisa or a. If, asa result of the specification of the -n option or end-of-file being reached, input data only 
partially satisfies a format string, the input block is zero-padded sufficiently to display all available data (that is, any format 
units overlapping the end of data will display somenumber of the zero bytes). 


Further output by such format strings is replaced by an equivalent number of spaces. An equivalent number of spaces is 
defined as the number of spaces output by an s conversion character with the same fidd width and precision as the original 
conversion character or conversion string but with any +, “", # conversion flag characters renoved, and referencing a NULL 
string. 

If no format strings are specified, the default display is equivalent to specifying the -x option. 

hexdump exits @ on success and >a if an error occurred. 


EXAMPLES 
Display the input in perusal format: 


"%06.6_a0 " 12/1 "%3_u " 
"\t\t" "%p" 
"\n" 


Implement the -x option: 


"8607 ..7_AX\n" 
"307.7 ax " 8/2 "%04x ""\n" 


SEE ALSO 
adb(1) 
18 April 1994 


hipstopgm 
hipstopgm— Convert aH IPS file into a portable graymap 


SYNOPSIS 


hipstopgm [hipsfile] 


DESCRIPTION 
Hipstopgm reads aH IPS file asinput and produces a portable graymap as output. 
If theH IPS file contains more than oneframein sequence, hipstopgm will concatenate all the frames vertically. 
HIPS isa format devdoped at the H uman Information Processing Laboratory, NYU. 


SEE ALSO 
pam(5) 
AUTHOR 
Copyright © 1989 by J ef Poskanzer 
24 August 1989 
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host 


host— Look up hostnames using domain server 


SYNOPSIS 


host [-1] [-v] [-w] [-r] [-d] [-t querytype] [-a] host [ server ] 


DESCRIPTION 


host looks for information about Internet hosts. It gets this information from a set of interconnected servers that are spread 
across the country. By default, it simply converts between hostnames and Internet addresses. H owever with the -t or -a 
options, it can be used to find all of the information about this host that is maintained by the domain serve. 


The arguments can be athe: hostnames or host numbers. The program first attempts to interpret then as host numbers. If 
this fails, it will treat them as hostnames. A host number consists of first decimal numbers separated by dots, for example 
128.6.4.194. A hostname consists of names separated by dots, for example, topaz.rutgers.edu. Unless the nameendsin a 
dot, the local domain is automatically tacked on the end. Thus, a Rutgers user can say "host topaz", and it will actually look 
UP topaz.rutgers.edu. If this fails, thenameis tried unchanged (in this case, topaz). T his same convention is used for mail 
and other network utilities. The actual suffix to tack on the end is obtained by looking at the results of ahostname call, and 
using everything starting at the first dot. (Following is a description of how to customize the hostname lookup.) 


The first argument is the hostname you want to look up. If thisis anumber, an inverse query is done; that is, the domain 
system looks in a separate set of databases used to convert numbers to names. 


The second argument is optional. It allows you to specify a particular server to query. If you don’t specify this argument, the 
default server (normally the local machine) is used. 





If anameis specified, you may see output of three different kinds. H ere is an example that shows all of them: 


% host sun4 

sun4.rutgers.edu is a nickname for ATHOS.RUTGERS.EDU 
ATHOS.RUTGERS.EDU has address 128.6.5.46 
ATHOS.RUTGERS.EDU has address 128.6.4.4 
ATHOS.RUTGERS.EDU mail is handled by ARAMIS.RUTGERS.EDU 


Theuser hastyped the command host sun4. The first line indicates that the name sun4. rutgers. edu is actually anickname 
The official hostname is ATHOS. RUTGERS .EDU. T he next two lines show the address. If a system has morethan one network 
interface, there will be a separate address for each. T he last line indicates that ATHOS.RUTGERS .EDU does not receive its own 
mail. M ail for it istaken by ARAMIS.RUTGERS.EDU. T here may be morethan onesuch line as some systems have more than one 
other system that will handle mail for them. Technically, every system that can receive mail is supposed to have an entry of 
this kind. If the system receives its own mail, there should be an entry the mentions the system itself, for example “XXX mail 
is handled by XXX.” H owever many systems that receive their own mail do not bother to mention that fact. If a system has a 
“mail is handled by” entry, but no address, this indicates that it is not really part of the Internet, but a system that is on the 
network will forward mail to it. Systems on U senet, bitnet, and anumber of othe: networks have entries of this kind. 


There area number of options that can be used before the hostname M ost of these options are meaningful only to the staff 
who have to maintain the domain database 


The option -w causes host to wait forever for a response. N ormally it will time out after around a minute. 


Theoption -v causes printout to bein a verbose format. T his isthe official domain master file format, which is documented 
in theman page for named. Without this option, output still follows this format in general terms, but some attempt is made 
to make it more intdligible to normal users. Without -v, a, mx, and cname records are written out aShas address, mail is 
handled by, and is a nickname for, and TT L and class fields are not shown. 


Theoption -r causes recursion to beturned off in the request. T his means that the name server will return only datait hasin 
its own database. It will not ask other servers for more information. 


Theoption -a turnson debugging. N etwork transactions are shown in detail. 
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The option -t allows you to specify a particular type of information to be looked up. T he arguments are defined in the man 
page for named. Currently supported types are a, ns, md, mf, cname, soa, mb, mg, mr, null, wks, ptr, hinfo, minfo, mx, uinfo, uid, 
gid, unspec, and the wildcard, which may be written as ether any or *. T ypes must be given in lowercase. N ote that the 
default isto look first for a, and then mx, except that if the verbose option is turned on, the default is only a. 


The option -a (for “all”) is equivalent to -v -t any. 

The option -1 causes a listing of acomplete domain. For example 

host -1 rutgers.edu 

will givea listing of all hostsin the rutgers.edu domain. The -t option is used to filter what information is presented, as you 
would expect. T he default is address information, which also include PTR and NS records. The command host: 

-l -v -t any rutgers.edu 


will give a complete download of the zone data for rutgers.edu, in the official master file format. (H owever the SOA record 
is listed twice, for arcane reasons.) 


NOTE 


-1 is implemented by doing a complete zone transfer and then filtering out the information you have asked for. This 
command should be used only if it is absolutely necessary. 


CUSTOMIZING HOSTNAME LOOKUP 


In general, if the name supplied by the user does not have any dots in it, a default domain is appended to the end. This 
domain can be defined in /etc/resolv.conf, but is normally derived by taking the local hostname after its first dot. T he user 
can override this, and specify a different default domain, using the environment variable LocaLpomarn. In addition, the user 
can supply his own abbreviations for hostnames. T hey should be in a file consisting of oneline per abbreviation. Each line 
contains an abbreviation, a space and then the full hostname. This file must be pointed to by an environment variable 
HOSTALIASES, which is the name of the file 


SEE ALSO 


named(8) 


BUGS 


Unexpected effects can happen when you type a name that is not part of thelocal domain. Please always keep in mind that 
the local domain name is tacked onto the end of every name unless it ends in a dot. Only if this fails isthe name used 
unchanged. 


The -1 option only tries the first name server listed for the domain that you have requested. If this server is dead, you may 
need to specify a server manually. For example, to get alisting of foo.edu, you could try host -t ns foo.edu to get alist of all 
the name serves for foo.edu, and then try host -1 foo.edu xxx for all xxx on the list of name servers, until you find one that 
works, 


hostid 


hostid— Set or print system’s host ID. 
SYN TAX 


hostid [-v] [ decimal-id ] 


hostname 
DESCRIPTION 


The hostid command prints the current host |D number in hexadecimal and both decimal and hexadecimal in parenthesis if 
the -v option is given. T hisnumeric value is expected to be unique across all hosts and isnormally set to resemble the host’s 
Internet address. 


Only the superuser can set the hostid by giving an argument. T his value is stored in the file /etc/hostid and need only be 
performed once. 


AUTHOR 


hostid is written by M itch D ‘Souza (m.dsouza@mrc-apu.cam.ac.uk). 


SEE ALSO 


gethostid(2), sethostid(2) 


hostname 


hostname— Show or set the system’s hostname 
dnsdomainname --Show the system’s domain name 


SYNOPSIS 
hostname [-d][--domain][-Ffilename] [--filefilename] [-f][--fqdn][-h][--help] 
[--long][-s][--short][-v][--version] [name] 
dnsdomainname 

DESCRIPTION 


hostname is the program that is used to either set the hostname or display the current host or domain name of the system. 
This name is used by many of the networking programs to identify the machine 


W hen called without any arguments, the program displays the current name as set by the hostname command. You can 
change the output format to display always the short or the long hostname (FQ DN ). When called with arguments, the 
program will set the value of the hostname to the value specified. T his usually is done only once, at system startup time by 
the /etc/rc.d/rc.inet1 configuration script. 

N ote that only the superuser can change the hostname. 


If the program was called as dnsdomainname, it will show the domain name server (DN S) domain name. You can’t change the 
DNS domain name with dnsdomainname. (See the following subsection.) 


OPTIONS 
-d, --domain Display the name of the DN S domain. Don’t use the com-mand domainname to get the DNS 
domain name because it will show the NIS domain name and not the DNS domain name 
-F, --file filename Read the hostname from the specified file Comments (lines starting with a#) are ignored. 


-f, --fqdn, --long Display the FQDN (fully-qualified domain name). An FQDN consists of ashort hostname and 
the DNS domain name Unless you are using bind or N1IS for host lookups, you can change the 
FQDN and theDNS domain name (which is part of the FQDN) in the /etc/hosts file 





-h, --help Print a usage message on standard output and exit successfully. 

-s, --short Display the short hostname 

-v, --version Print version information on standard output and exit successfully. 
FILES 


/etc/hosts 
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AUTHOR 


Peter T obias, (tobias@server.et-inf.fho-emden. de) 


hpcdtoppm v0.3 
hpcdtoppm VO.3— Convet a Photo-CD file into a portable pixmap 


SYNOPSIS 


hpcdtoppm [options] pcd-file [ppm-file] 


DESCRIPTION 


hpcdtoppm reads a Photo-C D image file or overview file and outputs a portable pixmap. Image files you can find on the 
Photo-CD in photo_cd/images are named aS imgnnnn.pcd, where nnnn iS a 4-digit-number. T he O verview file is at photo_cd/ 
overview.pcd. If there isno ppm-file given, output will be printed to stdout. hpcdtoppm stands for “H admut’s pcedtoppm” to 
make it distinguishable in case someone ase is building the same thing and calling it pcdtoppm. 


1 


-ycc 


OPTIONS 


-Base/16 | -128x192 


-Base/4 | -256x384 
-Base | -512x768 
-4Base | -1024x1536 
-16Base | -2048x3072 


-Overview | -0 


Linux, 28 July 1994 


Give some information from the fileneader to stderr. It works only for image files. (It is not 
working correctly, just printing some strings.) 

Apply simple sharpness-operator on the luma channd.. 

Do not show the complete image, but only the decompressed difference It works only on 
the 4Base and the 16Base resolution. It does not have any deeper sense but it was simple to 
implement and it shows what causes different sizes of image files. 

Rotate the picture clockwise for portraits. 

Rotate the picture counte-clockwise for portraits. 

Try to find out the image orientation. T his doesn’t work for overview files yet. It is very 
experimental and depends on one byte. Please tell me if it doesn’t work. 

O verskip mode. W orks on Base/16, Base/4, Base, and 4Base. In Photo-CD images, the 
luma channd is stored in full resolution, the two chroma channds are stored in half 
resolution only and have to be interpolated. In the O verskip mode, the chroma channds of 
the next higher resolution are taken instead of interpolating. To see the difference generate 
One ppm with and one ppm without this flag. Use pnmarith to generate the difference image of 
these two images. Call ppmhist for this difference or show it with xv (push the H istEq 
button in the color editor). 

Extract the Base/16 size picture (size 128x192 pixels). N ote that you can only give onesize 
option. 

Extract the Base/4 size picture 

Extract the Base size picture. 

Extract the 4B ase size picture. 

Extract the 16B ase size picture. 

Extract all pictures from an O verview file. A ppm filaaame must be given. If the given name 
iS foo, the files are named foonnnn, where nnnn iS a 4-digit number. T hey are stored in 
Base/16 format, so they are extracted in this format. 

Suppress the ycc to rgb conversion. This is experimental only. You can use this and apply 
ppmtorgb3 on thefile Then you will get three pgm files, oneluma and two chromafiles. 


httpd Ei 
BUGS 


| still don’t have enough information about the Photo-CD to take care of all data structures. The information | have is quite 
vague and this program was devdoped by staring at the hexdumps and using the famous trial-and-error-method. :-) If 
anything doesn’t work, please send mea report and perhaps you could try to find out why it doesn’t work. 


SEE ALSO 


ppm(5), ppmquant(1), ppmtopgm(1), ppmhist(1), pnmarith(1), ppmtorgb3(1), xv(1) 


AUTHOR 


Copyright© 1992 by H admut D anisch (danisch@ira.uka.de). Permission to use and distribute this software and its 
documentation for noncommercial use and without fee is hereby granted, provided that the preceding copyright notice 
appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. 
This software may not be sold in any way. T his software is not public domain. 


28 N ovenber 1992 


httpd 


httpd— Apache H ypertext Transfer Protocol server 


SYNOPSIS 


httpd [ -vX? ][-d serverroot ][-f config ] 


DESCRIPTION 


httpd isthe Apache H ypertext T ransfer Protocol (HT TP) server process. The server may be invoked by the Internet daenon 
inetd(1M ) each timea connection to the HT TP serviceis made, or alternatively it may run asa daemon. 


OPTIONS 


-d serverroot Se the initial value for the serverRoot variable to serverroot. This can be overridden by the ServerRoot 
command in the configuration file The default is /usr/local/etc/httpd. 


-f config Execute the commands in thefileconfig on startup. If config doesnot begin with a/, then it istaken to 
bea path relative to the Serverroot. T he default is conf /httpd.conf. 
-X Run in sngle-process mode, for internal debugging purposes only; the daanon does not detach from the 
terminal or fork any children. D o not use this mode to provide ordinary W éb service. 
-v Print the version of httpd, and then exit. 
-? Print alist of the httpd options, and then exit. 
FILES 


/usr/local/etc/httpd/conf /httpd.conf 
/usr/local/etc/httpd/conf/srm.conf 
/usr/local/etc/httpd/conf /access. conf 
/usr/local/etc/httpd/conf /mime.types 
/usr/local/etc/httpd/logs/error_log 
/usr/local/etc/httpd/logs/access_log 
/usr/local/etc/httpd/logs/httpd.pid 


SEE ALSO 
inetd(1m) 
Documentation for the Apache HTTP server is available from http: //www.apache.org. 
Octobe 1995 
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icontopbm 


icontopbm— Convert a Sun icon into a portable bitmap 


SYNOPSIS 
icontopbm [iconfile] 
DESCRIPTION 
icontopbm reads a Sun icon asinput and produces a portable bitmap as output. 
SEE ALSO 
pbmtoicon(1), pbm(5) 
AUTHOR 
Copyright© 1988 by J ef Poskanzer 
31 August 1988 
ident 
ident— Identify RCS keyword strings in files 
SYNOPSIS 
ident [ -q ][-V ][file ... ] 
DESCRIPTION 
ident searches for all instances of the pattern $ keyword : text $ in thenamed files or, if no files are named, the standard 
input. 


T hese patterns are normally inserted automatically by the RCS command co(1), but can also beinserted manually. The 
option -q suppresses the warning given if there areno patternsin afile The option -v prints ident’s version number. 


ident works on text files as well as object files and dumps. For example if theC program in f.c contains 


#include <stdio.h> 

static char const rcsid[] = 

"$Id: f.c,v 5.4 1993/11/09 17:40 eggert Exp $"; 

int main() { return printf("%s\n", rcsid) == EOF; } 


and f.c iS compiled into f.0, then the command 
ident f.c f.o 
will output 


TCs 
$Id: f.c,v 5.4 1993/11/09 17:40 eggert Exp $ 
f.0: 
$Id: f.c,v 5.4 1993/11/09 17:40 eggert Exp $ 


If aC program defines a string like the resid but does not useit, 1int(1) may complain, and someC compilers will optimize 
away the string. The most reliable solution is to have the program use the resid string, as shown in the example 


ident finds all instances of thes keyword : text $ pattern, even if keyword is not actually an RC S-supported keyword. This 
gives you information about nonstandard keywords like $xconsortium$. 


ilbmtoppm 
KEYWORDS 


H ereisthe list of keywords currently maintained by co(1). All times are given in Coordinated U niversal Time(UTC, 
sometimes called GMT by default), but if the files were checked out with co’s -zzone option, times are given with anumeric 
time zone indication appended. 


$Author$ Thelogin name of the user who checked in the revision. 
Date$ The date and time the revision was checked in. 
Header$ A standard header containing the full pathname of the RCS file, the revision number, the date and time, 
the author, the state, and the locker (if locked). 
$Id$ Same as $Header$, except that the RCS filename is without a path. 
Locker$ Thelogin name of the user who locked the revision (empty if not locked). 
$Log$ The log message supplied during checkin. For ident’s purposes, thisis equivalent to $rcsfile$. 
Name$ The symbolic name used to check out the revision, if any. 
RCSfile$ Thename of theRCS file without a path. 
Revision$ Therevision number assigned to the revision. 
$Source$ The full pathname of the RCS file 
States The state assigned to the revision with the -s option of rcs(1) or ci(1). 





co(1) represents the following characters in keyword values by escape sequences to keep keyword strings well formed. 





Character Escape Sequence 

Tab \t 

N ewline \n 

Space \040 

$ \044 

\ \\ 
IDENTIFICATION 


Author: W alter F. Tichy 
M anual Page Revision: 5.4; Release date Seotember 11, 1993. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. Copyright© 1990, 1992, 1993 Paul Egget. 
SEE ALSO 
ci(1), co(1), res(1), resditt(1), resintro(1), resmerge(1), rlog(1), resfile(5) 
Walter F. Tichy, RCS— A Systen for Version Control, Software-Practice & Experience 15, 7 (July 1985), 637-654. 
GNU, 9 N ovenber 1993 


ilbmtoppm 


ilbmtoppm— Convert an ILBM file into a portable pixmap 


SYNOPSIS 


ilbmtoppm [-verbose][-ignore<chunkID>] [-isham}-isehb][-adjustcolors] [ILBMfile] 


DESCRIPTION 


ilbmtoppm reads an IFF ILBM file asinput and produces a portable pixmap as output. Supported ILBM types are N ormal 
ILBM swith 1-16 planes. 
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Amiga Extra H alfbrite (EH B) 

AmigaH AM with 3-16 planes 

24-bit 

M ultiplatte (normal or HAM ) pictures 

Colormap (BMHD and cmap chunk only, nPlanes = @) 

Unofficial direct color; 1-16 planes for each color component. 


Chunks used: BMHD, CMAP, CAMG (only HAM and EHB flags used), pcHe, Bopy unofficial pco. chunk to 
identify direct color |LBM 
Chunks ignored: GRAB, DEST, SPRT, CRNG, CCRT, CLUT, DPPV, DRNG, EPSF 


Other chunks (ignored but 
displayed in verbose mode): NAME, AUTH, (d), ANNO, DPI 


Unknown chunks are skipped. 


OPTIONS 
-verbose Give some information about the LBM file 
-ignore <chunkID> Skip achunk. <chunk1p> is the 4-letter 1rF chunk identifier of the chunk to be skipped. 
-isham | -isehb Treat theinput file as a Ham or Extra H alfbrite picture, even if these flags or not set in the cama 
chunk (or if there isno came chunk). 
-adjustcolors If all colorsin the cmap havea value of lessthen 16, ilbmtoppm assumes a 4-bit colormap and gives a 
warning. W ith this option, the colormap is scaled to 8 bits. 
BUGS 
The multipalette PC H G BigLineChanges and H uffman decompression code are untested. 
REFERENCES 
Amiga ROM Kernd ReferenceM anual— D evices (3rd Ed.). Addison Wesley, ISBN 0-201-56775-X. 
SEE ALSO 
ppm(5), ppmtoilbm(1) 
AUTHORS 


Copyright© 1989 by J ef Poskanzer. 
M odified O ctober 1993 by Ingo W ilken (Ingo.Wilken@informatik.uni-oldenburg. de) 
4 Octobe 1993 


imake 


imake— C preprocessor interface to the make utility 


SYNOPSIS 
imake [ -Ddefine ][-Idir ][-Ttemplate ][-f filename ][-C filename ][-s filename ] 
[-e ][-v ] 

DESCRIPTION 


imake iS used to generate Makefiles from atemplate a set of cpp macro functions, and a per-directory input file called an 
Imakefile. T his allows machine dependencies (such as compiler options, alternate command names, and special make rules) to 
be kept separate from the descriptions of the various items to be built. 


imake 


OPTIONS 


The following command-line options may be passed to imake: 











-Ddefine This option is passed directly to cpp. It is typically used to set directory-specific variables. For example, the 
X Window System uses this flag to set Topp1r to thename of the directory containing the top of the core 
distribution and curpir to the name of the current directory, relative to the top. 

-Idirectory This option is passed directly to cpp. It is typically used to indicate the directory in which the imake 
template and configuration files may be found. 

-Ttemplate This option specifies the name of the master template file (which is usually located in the directory 
specified with -1) used by cpp. The default is make. tmp1. 

-f filename This option specifies the name of the pe-directory input file. The default is makefile. 

-C filename This option specifies the name of the .c file that is constructed in thecurrent directory. T he default is 
Imakefile.c 

-s filename This option specifies the name of the make description file to be generated but make should not beinvoked. 
If the filename isa hyphen (-), the output is written to stdout. The default is to gnerate, but not execute, 
a Makefile. 

-e This option indicates the imake should execute the generated makefile. T he default is to leave this to the 
user. 

-v This option indicates that imake should print the cpp command line that it is using to generate the 
Makefile. 

HOW IT WORKS 


Imake invokes cpp with any -1 or -p flags passed on the command line and passes the name of a file containing the following 
three lines: 


#define IMAKE_TEMPLATE "Imake.tmpl" 


#define INCLUDE_IMAKEFILE <Imakefile> 
#include IMAKE_TEMPLATE 


where Imake.tmp1 and Imakefile may be overridden by the-t and -f command options, respectively. 


The IMAKE_TEMPLATE typically reads in a file containing machine-dependent parameters (specified as cpp symbols), a site 
specific parameters file, a file defining variables, a file containing cpp macro functions for generating make rules, and finally 
the Imakefile (Specified by INCLUDE_IMAKEFILE) in the current directory. T he Imakefile uses the macro functions to indicate 
what targets should be built; imake takes care of generating the appropriate rules. 


Imake configuration files contain two types of variables, imake variables and make variables. The imake variables are interpreted 
by cpp when imake isrun. By convention they are mixed case. T he make variables are written into the makefile for later 
interpretation by make. By convention make variables are uppercase. 


The rules file (usually named Imake. rules in the configuration directory) contains a variety of cpp macro functions that are 
configured according to the current platform. Imake replaces any occurrences of the string ea with anewline to allow macros 
that generate more than one lineof make rules. For example, when called with program_target(foo, foot.o foo2.o), the 
macro: 

#define program_target(program, objlist) @@\ 

program: objlist @@\ 

$(CC) -o $@ objlist $(LDFLAGS) 


will expand to 


foo: foot.o fo02.0 
$(CC) -o $@ f001.0 foo2.0 $(LDFLAGS) 


imake also replaces any occurrences of the word xcoum with the character # to permit placing comments in the makefile 
without causing invalid directive errors from the preprocessor. 
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Some complex imake Macros require generated make variables local to each invocation of the macro, often because thar value 
depends on parameters passed to the macro. Such variables can be created by using an imake variable of the form xvardefn, 
wheren isasingle digit. A unique make variable will be substituted. Later occurrences of the variable xvarusen will be replaced 
by the variable created by the corresponding xvardefn. 


On systems whose cpp reduces multiple tabs and spaces to a single space, imake attempts to put back any necessary tabs (make 
is very picky about the difference between tabs and spaces). For this reason, colons (:) in command lines must be preceded 
by a backslash (\). 


USE WITH THE X WINDOW SYSTEM 


The X Window System uses imake extensivay, for both full builds within the source tree and external software. As men- 
tioned earlier, two special variables, Toppir and curpir, are set to make referencing files using relative pathnames easier. For 
example, the following command is generated automatically to build the makefile in the directory 1ib/x/ (rdative to the top 
of the sources): 


% ../.././config/imake -I../.././config \ 
-DTOPDIR=../../. -DCURDIR=./1ib/X 


When building X programs outside the source tree, a special symbol UseInstalled is defined and Toppir and curDIR are 
omitted. If the configuration files have been properly installed, the script xmkmf(1) may be used. 


INPUT FILES 
H ereisasummary of the files read by imake as used by X. Theindentation shows which files include which other files. 


Imake.tmpl generic variables 

site.def site-specific, BeforeVendorCF defined 
-cf machine-specific 

Lib.rules shared library rules 

site.def site-specific, AfterVendorCF defined 
Imake.rules rules 

Project.tmpl X-specific variables 

Lib.tmpl shared library variables 

Imakefile 

Library.tmpl library rules 

Server.tmpl server rules 

Threads.tmpl multi-threaded rules 


N ote that site.def isincluded twice, once beforethe «.ct file and onceafter. Although most site customizations should be 
specified after the «ct file some, such as the choice of compiler, need to be specified before, because other variable settings 
may depend on them. 


Thefirst time site.def isincluded, the variable BeforeVendorcF is defined, and the second time, the variable aftervendorcr iS 
defined. All codein site.det should be inside a#ifdet for one of these symbols. 


FILES 


Imakefile.c Temporary input file for cpp 

/tmp/Imf .XXXXXxX Temporary Makefile for -s 

/tmp/IIf.XXXXxx Temporary Imakefile if specified Imakefile uses # Comments 
/lib/cpp Default C preprocessor 


SEE ALSO 
make(1), xmkmf(1) 


S.1. Feldman, M ake— A Program for M aintaining Computer Programs 
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ENVIRONMENT VARIABLES 
The following environment variables may be set; however, their use is not recommended as they introduce dependencies that 
are not readily apparent when imake is run. 
IMAKE INCLUDE If defined, this should be a valid include argument for the C preprocessor. Example 
-I/usr/include/local 
Actually, any valid cpp argument will work here. 
IMAKECPP If defined, this should be a valid path to a preprocessor program. Example 
/usr/local/cpp 
By default, imake will use /1ib/cpp. 
IMAKEMAKE If defined, this should bea valid path to a make program, such as 
/usr/local/make 
By default, imake will use whatever make program is found using execvp(3). This variable is only used if the 


-e option is specified. 


AUTHORS 
Todd Brunhoff, Tektronix and MIT Project Athena 


Jim Fulton, MIT X Consortium 
X Verson 11 Release 6 


imgtoppm 
imgtoppm— Convert an Img-whatnot file into a portable pixmap 


SYNOPSIS 


imgtoppm [imgfile] 


DESCRIPTION 


imgtoppm reads an Img-whatnot file as input and produces a portable pixmap as output. The 1mg-whatnot toolkit is available for 
FTP on venera. isi.edu, along with numerous images in this format. 
SEE ALSO 
ppm(5) 
AUTHOR 
Based on asimple conversion program posted to comp.graphics by Ed Falk. 


Copyright© 1989 by J ef Poskanzer. 
5 Seotember 1989 


inews 


inews— Send aU senet article to the local news server for distribution 


SYNOPSIS 


inews [ -h ][-D ][-O ][-R ][-S ][header flags ][input ] 
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DESCRIPTION 


Inews reads aU senet news article (perhaps with headers) from the named file or standard input if no file is given. It adds 
some headers and performs some consistency checks. If the article does not meet these checks (for example too much 
quoting of old articles, or posting to nonexistent newsgroups), then the article is rejected. If it passes the checks, inews sends 
the article to the local news server as specified in the inn.cont(5) file for distribution. 

In the standard mode of operation, the input consists of the article headers, a blank line, and the message body. For com- 
patibility with older software, the -h flag must be used. If there are no headers in the message, then this flag may be omitted. 
Several headers may be specified on the command line shown in the synopsis above as header flags. Each of these flags takes 
a single parameter; if the value is more than one word (for example, almost all Subject lines) then quotes must be used to 
prevent the shal from splitting it into multiple words. T he options, and thar equivalent headers, are as follows: 

Approved 

Control 

Distribution 

Expires 

From 

Followup-To 

N ewsgroups 

Reply-To 

Subject 

References 

Organization 

Path prefix 


omrn SD Se F7MOQaQ0 wD 


x< 


The Path header is built according to the following rules. If the- x flag is used, then its value will be the start of the header. 
Any other host will see the sitein the header, and therefore not offer the article to that site If the pathnost configuration 
parameter is specified in the inn.cont(5) file then it will be added to the Path. O therwise, if the server configuration 
parameter is specified, then the full domain name of the local host will be added to the Path. The Path will always end 


not-for-mail. 
T he default O rganization header will be provided if noneis present in the article or if the -o flag is not used. T 0 prevent 
adding the default, use the -o flag. 


As adebugging aide, if the -p flag is used, the consistency checks will be performed, and the article will be sent to the 
standard output, rather then sent to the server. 


For compatibility with C N ews, inews accepts, but ignores, the -a, -v, and -w flags. TheC N ews -n flag is treated as the -p flag. 


If afile named .signature exists in the user’s home directory, inews will try to append it to the end of the article If the file 
cannot be read, or if it istoo long (for example, more than four lines or one standard I/O buffer), or if some other problen 
occurs, then the article will not be posted. To suppress this action, use the -s flag. 


If the -r flag isused then inews will reject any attempts to post control messages. 


If an unapproved posting is made to amoderated newsgroup, inews will try to mail the article to the moderator for posting. 
It uses the moderators(5) file to determine the mailing address. If no address is found, it will use the inn. conf file to 
determine a “last-chance” host to try. 


If the NNTP server needs to authenticate the client, inews will use the NNTPsendpass-word(3) routine to authenticate itself. In 
order to do this, the program will need read access to the passwd.nntp(5) file. T hisis typically done by having the file group- 
readable and making inews run setgid to that group. 


Inews exits with a zero status if the article was successfully posted or mailed, or with a nonzero status if the article could not 
be delivered. 


info 


Since inews will spool its input if the server is unavailable, it is usually necessary to run rnews(1) with the -u flag on a regular 
basis, usually out of cron(8). 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews 


SEE ALSO 


moderators(5), inn.conf(5). rnews(1) 


info 
info— GN U's hypertext systen 
SYNOPSIS 


info [ --option-name option-value ] enu-item... 


DESCRIPTION 


TheGNU project has a hypertext system called info that allows the same source file to be ather printed as a paper manual, 
or viewed using info. It is possible to use the info program from inside Emacs, or to use the standalone version described 
here. This manual page gives a brief summary of its capabilities. 


OPTIONS 


--directory directory-path Add directory- path to thelist of directory paths searched when info needs to find afile. 
You may issue --directory multiple times. Alternatively, you may specify a value for the 
environment variable INFOPATH; if --directory isnot given, the value of InFoPaATH is used. 
The value of INFoPATH iS a colon-separated list of directory names. If you do not supply 
either INFOPATH Or --directory- path, info usesa default path. 


-f filename Specify a particular info fileto visit. By default, info visits the file dir; if you use this 
option, info will start with (FILENAME)Top asthe first file and node 

-n nodename Specify a particular node to visit in the initial file that info loads. This is especially useful in 
conjunction with --file. You may specify --node multiple times. 

-o file Direct output to file instead of starting an interactive info session. 

-h Produce a relatively brief description of the available info options. 

--version Print the version information of info and exit. 

menu-item info treats its renaining arguments as the names of menu items. The first argument isa 


menu item in the initial node visited, while the second argument isa menu item in the first 
argument’s node You can easily moveto the node of your choice by specifying the menu 
names that describe the path to that node For example, info emacs buffers first sdects the 
menu item emacs in the node (dir) Top, and then selects the menu item buffers in the node 
(emacs) Top. 


COMMANDS 
In info, the following commands are available: 
h Invoke the info tutorial. 
2 Get ashort summary of info commands. 
h Sdect the info node from the main directory; this is much more complete than just using ?. 
Ctri-g | Abort whatever you are doing. 
Ctrl-1 Redraw thescreen. 
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Sdecting other nodes: 


n M ove to the next node of this node. 

p M oveto the previous node of this node. 

u M ove to thisnode’s up node. 

m Pick amenu item specified by name. Picking a menu item causes another node to be selected. You do not need to 


type a complete nodename; if you type a few letters and then a space or tab, info will try to fill in the rest of the 
nodename. If you ask for further completion without typing any more characters, you'll be given a list of 
possibilities; you can also get the list with 2. If you type afew characters and then hit Enter, info will try to doa 
completion, and if it is ambiguous, use the first possibility. 

f Follow a cross reference You are asked for the name of the reference using command completion as for m. 

1 M ove to the last node you were at. 


M oving within anode 
Space Scroll forward a page. 


DEL Scroll backward a page. 

b Go to the beginning of this node 

Advanced commands: 

q Quit info. 

1 Pick first item in node's menu. 

2-5 Pick second to fifth item in node's manu. 

g M ove to node specified by name You may include a filavame as well, aS (FILENAME) NODENAME. 

s Search through this info file for a specified string, and sdect the node in which the next occurrence is 
found. 


M-x print-node Pipethe contents of the current node through the command in the environment variable 
INFO_PRINT_COMMAND. If the variable does not exist, the node is simply piped to pr. 


ENVIRONMENT 


INFOPATH A colon-separated list of directories to search for info files. Used if --directory isnot given. 
INFO_PRINT_CONMAND The command used for printing. 


SEE ALSO 


emacs(1) 


AUTHOR 


Brian Fox, Free Software Foundation (bfox@ai.mit.edu) 
MANUAL AUTHOR 
Robert Lupton (rhig@astro.princeton.edu); updated by Robart J. Chassell (bob@gnu.ai.mit.edu). 
7 December 1990 


inncontval 


innconfval— Get an I nterN etN ews configuration parameter 


SYNOPSIS 


innconfval [ -f ][parameter... ] 
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DESCRIPTION 


Innconfval prints the values of the parameters specified on the command line. V alues are retrieved from the inn. cont(5) file 
and are described there. 


Values are retrieved by using the GetConfigvalue routine, or GetFileConfigValue if the -f flag is used. Both are described in 
libinn(3). 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews 


SEE ALSO 


libinn(3), inn. cont (5) 


insmod 


insmod— Install loadable modules (aout and ELF format) 


SYNOPSIS 
insmod [ -fkmsxv ] [ -o internal_name ] object_file [ symbol=value ... ] 
DESCRIPTION 


insmod installs a loadable module in the kernd. 


insmod tries to load a module into the kernel, and resolves all symbols from the exported kernd symbols, with version 
information, if available The module will get its name by removing the .o extension from the basename of the object file. If 
the .o extension is omitted, insmod will attempt to locate the module in some common default directories. If the environ- 
ment contains the variable woppatH, where all directories are separated with :, insmod will look in these directories for the 
module, in the specified order. 


It is possible to load unversioned modules in a versioned Kernel, and all combinations of these 
It is also possible to load ELF modules into an a.out kernel, and all combinations of these 


It is possible to stack modules, that is, l@ one module use a previously loaded module. All modules that are referenced are 
updated with this reference This ensures that a module can’t be unloaded if there is another module that refers to it. 





It is possible to change integer values in the module when loading it. T his makes it possible to tune the module. 
The options areas follows: 


-f The -¢ option tries to load the module even if the kernel or symbol versions differs from the 
version expected by the module. A warning will be issued if the module islocked to a 
specific kernel version that differs from the current version. 

-k This option should really only be used by modprobe, to indicate that the module insertion 
was requested by kerneld. All modules inserted using this option will be subject to 
autorenoval by the kerne1d utility if they have been unused for more that a minute. (The 
usage count is zero and no modules depend on this module) If the kernd isnot kernela- 
aware, the module will be rejected by the kernel. J ust load it without the -k option, and all 


should be wel. 

=m The -n option will make insmod output aload map, that will make it easier to debug your 
modules after a kernel panic, thanks to D erek Atkins (warlord@miT. Du). 

-0 The -o option allows the module to be named to an explicit name instead of having anane 


derived from the name of the object file. N ote that this option can also be placed after the 
module name, so that the syntax of insmod looks more similar to 14. 
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symbol=value[ ,value] ... The values of all integer or character pointer symbols in the module can be changed at load- 
time by naming a symbol and giving the new value(s). If the symbol is defined as an array of 
integers or character pointers, the elenents in the array can be initialized by giving the 
values separated by commas. Specific array entries can be skipped by omitting the value, as 
iN symbol=valuel,,value2. Each integer value can be given as a decimal, octal, or hexadeci- 
mal value: 17, 021, or ox11. If the first character in the given value is nonnumaiic, the value 
isinterpreted as a string. The symbol is assumed to bea character pointer, which will be 
initialized to point to the string. Extra space in the module will be allocated for the string 
itself. N ote the syntax: no spaces are allowed around the = or , signs! 


-s With this option, insmod will produce debugging information and error messages using the 
syslog facility. (Also used by kerneld, if you have installed it.) 

-v If you want verbose information from the loading, select this option. 

-x Theno-export flag, which will inhibit the default insmod behavior— inserting all the 


module's external symbols into the kernel symbol table. N ote that the kernd will still 
update the references that the module makes to previously loaded modules. 
SEE ALSO 


rmmod(1), modprobe(1), depmod(1), 1smod(1), ksyms(1), modules(2), genksyms(8) 


HISTORY 
The module support was first conceived by Anonymous (as far as! know). Linux version by Bas Laarhoven (bas@vimec.n1). 
0.99.14 version by Jon Tombs (jon@gtex02.us.es). Extended by Bjorn Ekwall (bjarn@blox.se). ELF hdp from Eric 
Youngdale (eric@aib.com). 


BUGS 


insmod relies on the “fact” that symbols, for which one wants to change the value, are defined as integers or character 
pointers, and that sizeof(int) == sizeof(char *). 


Linux, 14 May 1995 


install 


install— Copy files and set their attributes; GN U fileinstaller 
SYNOPSIS 


install [options] [-s] [--strip] source dest 
install [options] [-s] [--strip] source... directory 
install [options] [-d,--directory] directory... 


O ptions: 


[-c] [-g group] [-m mode] [-o owner] [--group=group] [--mode=mode ] 
[--owner=owner] [--help] [--version] 


DESCRIPTION 


This manual page documents the GN U version of install. install copies files and sets thar permission modes and, if 
possible, their owner and group. Used similarly to cp; typically used in makefiles to copy programsinto their destination 
directories. It can also be used to create the destination directories and any leading directories, and to set the final directory’s 
modes. It refuses to copy files onto thenselves. 
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OPTIONS 

-¢ Ignored; for compatibility with old UNIX versions of install. 

-d, --directory Create each given directory and its leading directories, if they do not already exist. Set the owner, 
group, and mode as given on the command line or to the defaults. Also gives any leading directories 
that are created those attributes. T his is different from the SunOS 4.x instal1, which gives 
directories that it creates the default attributes. 

-g, --group group Sé& the group ownership of the installed file or directory to the group ID of group (default is 
process's current group). group may also beanumaic group ID. 

-m, --mode mode Se the permission mode for the installed file or directory to mode, which can be ather an octal 
number, or asymbolic modeas in chmod, with @ as the point of departure. T he default mode is 
0755. 

-0, --owner owner If run as root, set the ownership of the installed file to the user ID of owner (default is root). owner 
may also be anumeric user ID. 

-s, --strip Strip the symbol tables from installed programs. 

--help Print a usage message on standard output and exit successfully. 

--version Print version information on standard output and exit successfully. 


GNU FileUtilities 
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installit— File/directory installation tool 


SYNOPSIS 


installit [ -o owner ][-g group ][-O owner ][-G group ][-m mode ][-b backup ] 
[-s ][-t ] source destination 


DESCRIPTION 


installit puts a copy of source into the specified destination. 


If source iSaperiod, then destination istaken to bethename of adirectory that should be created. Otherwise, source is 
taken to name an existing file and destination may be either afile or directory; it isinterpreted according to the same rules 
as cp(1). 


If destination namesa preexisting file, it will be removed before the copy is done To makea backup copy, use the -b flag; 
the existing file will be renamed to have the specified extension. If source and destination arethe same string, or if the two 
files are identical, then no copying is done, and only the -o, -g, -m, and -s flags are processed. In this case, the modification 
timeon the destination will be updated using touch(1) unless the -n (don’t touch) flag is used. 


After the destination has bee created, it is possible to set theowne, group, and mode that it should have. This is done by 
using the -o, -g, and -m flags, respectively. T he -o and -c flags set the owner and group only if insta11it is being run by root, 
as determined by whoami(1). To strip(1) an installed executable, use the -s flag. 


N ote that instal1lit uses no special privileges to copy files from one place to another. 


BUGS AND LIMITATIONS 


Flags cannot be combined. 
The chown(8) command must exist in either the /ete or /usr/ete directory or the user’s PATH. 
The whoami command must exist in the /usr/ucb directory or the user’s PATH. 
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HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews 


ispell, buildhash, munchlist, findaffix, tryaffix, 1combine, 


ispell, buildhash, munchlist, findaffix, tryaffix, icombine, ijoin--Interactive spelling checking 
SYNOPSIS 

ispell [common- flags ][-Mj-N][-Lcontext] [-V] files 

ispell [common-flags] -1 

ispell [common-flags][-f file] [-s]-a; -A 

ispell [-d file][-w chars] -c 

ispell [-d file][-w chars] -e[e] 

ispell [-d file] -D 

ispell -v[v] 





common - flags: [-t][-n] [-b] [-x][-B][-C][-P] 





[-Wn 


buildhash [-s] dict-file affix-file hash-file 


m][-S][-d file][-p file][-w chars] 
[-T type] 


buildhash -s count affix-file munchlist [-1 aff-file][-c conv-file] 


[-T su 
{-m mi 


ffix][-s hash-file] [-D][-v][-w chars ][files] findaffix [-p{-s][-f][-c] 
nJ[-M max][-e elim][-t tabchar][-1 low][files ] 








tryaffix [-p|-s] [-c] expanded-file affix[+taddition] 


icombine [-T type][aff-file] 


ijoin 








[-s;-u] join-options filel file2 


DESCRIPTION 
ispel1 is fashioned after the spell program from ITS (called ispel1 on T wenex systems.) Themost common usage is ispell 
filename. 1n this case, ispe11 will display each word which does not appear in the dictionary at the top of the screen and 
allow you to changeit. If there are “near misses” in the dictionary (words that differ by only a single letter, a missing or extra 


letter, 


a pair of transposed letters, or a missing space or hyphen), then they are also displayed on following lines. As well as 


near misses, ispel1 may display other guesses at ways to make the word from a known root, with each guess preceded by 


questi 


on marks. Finally, the line containing the word and the previous line are printed at the bottom of the screen. If your 


terminal can display in reverse video, the word itself ishighlighted. You have the option of replacing the word completely or 
choosing one of the suggested words. Commands are single characters as follows (case is ignored): 


R 
Space 


- oO <x - Ss CH > 
= 


Replace the misspelled word completely. 

Accept the word this time only. 

Accept the word for therest of this ispe11 session. 

Accept the word, capitalized asit isin the file and update private dictionary. 

Accept the word, and add an uncapitalized (actually, all lowercase) version to the private dictionary. 
Replace with one of the suggested words. 

Look up words in system dictionary (controlled by theworps compilation option). 

W rite the rest of this file, ignoring misspdlings, and start next file. 

Exit immediately and leave the file unchanged. 

Shell escape. 
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eh Redraw screen. 
v4 Suspend ispell. 
2 Givehdp screen. 


If the -m switch is specified, a one-line mini-menu at the bottom of the screen will summarize these options. Conversely, the 
-N switch may be used to suppress the mini-menu. (The mini-menu is displayed by default if ispe11 was compiled with the 
MINIMENU Option, but these two switches will always override the default.) 


If the -L flag is given, the specified number is used as the number of lines of context to be shown at the bottom of the screen. 
(The default is to calculate the amount of context as a certain percentage of the screen size) The amount of context is subject 
to a system-imposed limit. 


If the -v flag is given, characters that are not in the 7-bit AN SI printable character set will always be displayed in the style of 
cat -v, even if ispe11 thinks that these characters are legal |SO Latin-1 on your system. T his is useful when working with 
older terminals. W ithout this switch, ispe11 will display 8-bit characters as is if they have bem defined as string characters for 
the chosen file type. 





Besides the -1, -a, and -a options, N ormal mode accepts the following common flags on the command line: 


-t Theinput fileisin TeX or LaT eX format. 

-n The input file isin nroft/troff format. 

-b Create a backup file by appending .bak to thename of the input file 

-x D on’t create a backup file 

-B Report run-together words with missing blanks as spelling errors. 

-C Consider run-together words as legal compounds. 

-P D on’t generate extra root/affix combinations. 

=m M ake possible root/affix combinations that aren't in the dictionary. 

-S Sort the list of guesses by probable correctness. 

-d file Specify an alternate dictionary file. For example, use -d deutsch to choose a German dictionary in aGerman 
installation. 


-p file Specify an alternate personal dictionary. 

-w chars Specify additional characters that can be part of a word. 
-Won Specify length of words that are always legal. 

-T type | Assumeagiven formatter type for all files. 


The -n and -t options select whether ispel1 runs in nroft/troff (-n) or TeX/Lal eX (-t) input mode (The default is 
controlled by the perTExFLaG installation option.) TeX/LaT eX modeis also automatically selected if an input file has the 
extension .tex, unless overridden by the -n switch. In T eX/LaT eX mode, whenever a backslash (\) isfound, ispe11 skips to 
the next whitespace or T eX/LaT eX ddimiter. C etain commands contain arguments that should not be checked, such as 
labels and reference keys found in the \cite command, because they contain arbitrary, nonword arguments. Spell checking is 
also suppressed when in math mode. T hus, for example, given 


\chapter {This is a Ckapter} \cite{SCH86} 


ispell will find “ckapter” but not “sc.” The -t option does not recognizetheT eX comment character %, so comments are 
also spall checked. It also assumes correct LaT eX syntax. Arguments to infrequently used commands and some optional 
arguments are sometimes checked unnecessarily. T he bibliography will not be checked if ispe11 was compiled with 1cnoreB1B 
defined. Otherwise, the bibliography will be checked but the reference key will not. 


References for the tib(1) bibliography system (text between a[. or<. and .] or .>) will always be ignored in T eX/Lal eX mode. 
The -b and -x options control whether ispe11 leaves a backup (.bak) file for each input file. 


The .bak file contains the precorrected text. | f there are file opening/writing errors, the . bak file may be left for recovery 
purposes even with the -x option. T he default for this option is controlled by the pEFNoBackuPFLAG installation option. 
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The -8 and -c options control how ispe11 handles run-together words, such asnotthe for not the If -B is specified, such 
words will be considered errors, and ispe11 will list variations with an inserted blank or hyphen as possible reolacements. If 
-c is specified, run-together words will be considered to be legal compounds, so long as both components are in the 
dictionary, and each component is at least as long as a language dependent minimum (three characters, by default). Thisis 
useful for languages such as German and N orwegian, where many compound words are formed by concatenation. (N ote that 
compounds formed from three or more root words will still be considered errors). T he default for this option is language 
dependent; in a multilingual installation, the default may vary depending on which dictionary you choose. 





The -P and -m options control when ispe11 automatically generates suggested root/affix combinations for possible addition to 
your personal dictionary. (T hese are the entries in the “guess” list that are preceded by question marks.) If -p is specified, 
such guesses are displayed only if ispe11 cannot generate any possibilities that match the current dictionary. If -m is specified, 
such guesses are always displayed. This can be useful if the dictionary has a limited word list, or a word list with few suffixes. 
H owever, you should be careful when using this option, as it can generate guesses that produce illegal words. T he default for 
this option is controlled by the dictionary file used. 


The -s option suppresses ispe1l’s normal behavior of sorting the list of possible renlacenent words. Some people may prefer 
this, since it somewhat enhances the probability that the correct word will be low-numbered. 


The -a option is used to specify an alternate hashed dictionary file other than the default. If the filaaame does not contain a 
/, the library directory for the default dictionary file is prefixed; thus, to use a dictionary in the local directory -a ./xxx.hash 
must be used. T his is useful to allow dictionaries for alternate languages. U nlike previous versions of ispe11, a dictionary of 
/dev/null isillegal because the dictionary contains the affix table. If you need an effectively enpty dictionary, create a one 
entry list with an unlikely string (for example "qqqqq"). 


The -p option is used to specify an alternate personal dictionary file If the filavame does not begin with /, sHome is prefixed. 
Also, the shal variable worpList may be set, which renames the personal dictionary in the same manner. The command line 
overrides any worDLtsT setting. If neither the -p switch nor the worpLisT environment variable is given, ispe11 will search for a 
personal dictionary in both the current directory and sHome, creating one in $Home if none is found. The preferred name is 
constructed by appending . ispe11 to the base name of the hash file For example if you use the English dictionary, your 
personal dictionary would be named .ispell_english. H oweva@, if thefile .ispel1_words exists, it will be used as the personal 
dictionary regardless of the language hash file chosen. T his feature is included primarily for backwards compatibility. 





If the -p option isnot specified, ispe11 will look for personal dictionaries in both the current directory and thehome 
directory. If dictionaries exist in both places, they will be merged. When words are added to the personal dictionary, they will 
be written to the current directory if a dictionary already existed in that place otherwise, they will be written to the 
dictionary in the home directory. 


The -w option may be used to specify characters other than alphabetics that may also appear in words. For instance, -w "a" 
will allow “AT & T” to be picked up. U nderscores are useful in many technical documents. There isan admittedly crude 
provision in this option for 8-bit international characters. N onprinting characters may be specified in the usual way by 
inserting a backslash followed by the octal character code, for example, \014 for a form feed. Alternatively, if n appears in the 
character string, the (up to) three characters following are a decimal code, 0-255, for the character. For example, to include 
bdls and form feedsin your words (an admittedly silly thing to do, but aren’t most pedagogical examples): 


n007n012 


Numeric digits other than the three following n are simply numeric characters. U se of n does not conflict with anything 
because actual alphabetics have no meaning; alphabetics are already accepted. ispe11 will typically be used with input from a 
file, meaning that preserving parity for possible 8-bit characters from the input text is okay. If you specify the -1 option, and 
actually type text from the terminal, this may create problems if your stty settings preserve parity. 


The -w option may be used to change the length of words that ispe11 always accepts as legal. N ormally, ispe11 will accept all 
one-character words as legal, which is equivalent to specifying -w 1. (The default for this switch is actually controlled by the 
MINWORD installation option, so it may vary at your installation.) If you want all words to be checked against the dictionary, 
regardless of length, you might want to specify -w a. On the other hand, if your document specifies to accept all words of 
three letters or less, then regardless of the setting of this option, ispe11 will only generate words that are in the dictionary as 
suggested replacements for words; this prevents the list from becoming too long. O bviously, this option can be very 
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dangerous, since short misspellings may be missed. If you use this option alot, you should probably make a last pass without 
it before you publish your document, to protect yourself against errors. 


The -t option is used to specify a default formatter type for use in generating string characters. T his switch overrides the 
default type determined from the filename The type argument may be either one of the unique names defined in the 
language affix file (such as nroff) or a file suffix including the dot (for example, .tex). If no -T option appears and no type 
can be determined from the filename, the default string character type declared in the language affix file will be used. 


The -1 or list option to ispeil is used to produce a list of misspelled words from the standard input. 


The-a option is intended to be used from other programs through apipe. In this mode, ispe11 prints a oneline version 
identification message, and then begins reading lines of input. For each input line, a single line is written to the standard 
output for each word checked for spelling on the line. If the word was found in the main dictionary, or your personal 
dictionary, then the line contains only a*. If the word was found through affix removal, then the line contains a+, a space, 
and the root word. If the word was found through compound formation (concatenation of two words, controlled by the -c 
option), then the line contains only a-. 


If the word is not in the dictionary, but there are near misses, then theline contains an 3, a space, the misspdled word, a 
space, the number of near misses, the number of characters between the beginning of the line and the beginning of the 
misspelled word, acolon, another space, and alist of the near misses separated by commas and spaces. Following the near 
misses (and identified only by the count of near misses), if the word could be formed by adding (illegal) affixes to a known 
root, isa list of suggested derivations, again separated by commas and spaces. If there are no near misses at all, the line format 
is the same, except that the a is reolaced by 2 (and the near-miss count is always zero). T he suggested derivations following 
the near misses are in the form: 


[prefixt] root [-prefix] [-suffix] [+suffix] 
(for example, “retfry-yHes” to get “refries’) where each optional pfx and sfx isa string. Also, each near miss or guess is 


capitalized the same as the input word unless such capitalization is illegal; in the latter case each near miss is capitalized 
correctly according to the dictionary. 


Finally, if the word does not appear in the dictionary, and there are no near misses, then theline contains a#, a space, the 
misspelled word, a space, and the character offset from the beginning of the line Each sentence of text input is terminated 
with an additional blank line, indicating that ispe11 has completed processing the input line. 


T hese output lines can be summarized as follows: 


OK: * 

Root: + <root> 

Compound: - 

M iss: & <original><count><offset>: <miss>, <miss>, ..., <guess>, .. 
Guess: ? <original> 0 <offset>: <guess>, <guess>, ... 

None # <original> <offset> 


For example, a dummy dictionary containing the words fray, Frey, fry, and refried might produce the following response to 
thecommand echo 'frqy refries | ispell -a -m -d ./test.hash: 
(#) International Ispell Version 3.0.05 (beta), 08/10/91 


& frqy 3 0: fray, Frey, fry 
& refries 1 5: refried, re+fry-yties 


This modeis also suitable for interactive use when you want to figure out the spelling of a single word. 


The -a option works just like -a, except that if a line begins with the string "atnclude Filea", the rest of the line is taken as 
thename of a file to read for further words. Input returns to the original file when the include file is exhausted. I nclusion 
may be nested up to five deep. The key string may be changed with the environment variable 1ncLuDE_stRING (the anpe- 
sands, if any, must be included). 
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When in the-a mode, ispe11 will also accept lines of single words prefixed with any of the following: *, &, @, +, -,~, #, !, %, 
or *. A line starting with « tells ispe11 to insert the word into the user’s dictionary (similar to the 1 command). A line 
starting with & tds ispe11 to insert an all-lowercase version of the word into the user's dictionary (similar to theu com- 
mand). A line starting with @ causes ispe11 to accept thisword in the future (similar to the a command). A line starting with 
+, followed immediately by tex or nroff, will cause ispe11 to parse future input according the syntax of that formatter. A line 
consisting solely of a+ will place ispe11 in T eX/LaT eX mode (similar to the -t option) and - returns ispell to nroff/troff 
mode (but these commands are obsolete). H oweve,, string character type is not changed; the - command must be used to do 
this. A line starting with ~ causes ispe11 to set internal parameters (in particular, the default string character type) based on 
the filename given in the rest of the line (A file suffix is sufficient, but the period must be included. Instead of a filename or 
suffix, a unique name, as listed in the language affix file. may be specified.) H owever, the formatter parsing is not changed; 
the + command must be used to change the formatter. A line prefixed with # will cause the personal dictionary to be saved. A 
line prefixed with ! will turn on terse mode (explained later in this subsection), and a line prefixed with s will return ispel1 
to normal (non-terse) mode. Any input following the prefix characters +, -, #, !, or % iSignored, as is any input following the 
filename on a~ line To allow spell checking of lines beginning with these characters, a line starting with * has that character 
removed before it is passed to the spell checking code. It is recommended that programmatic interfaces prefix every data line 
with an up arrow to protect themselves against future changes in ispell. 


To summarize these 


* Add to personal dictionary 
@ Accept word, but leave out of dictionary 
# Save current personal dictionary 
Se parameters based on filename 
+ Enter TeX mode 
Exit TeX mode 
! Enter terse mode 


% Exit terse mode 
? Spell check rest of line 


In terse mode, ispel1 will not print lines beginning with *, +, or -, all of which indicate correct words. This significantly 
improves running speed when the driving program is going to ignore correct words anyway. 


The -s option is only valid in conjunction with the -a or -a options, and only on BSD -devived systems. If specified, ispe11 
will stop itself with a sretstp signal after each line of input. It will not read more input until it receives a staconT signal. This 
may be useful for handshaking with certain text editors. 





The -¢ option is only valid in conjunction with the -a or -a options. If -¢ is specified, ispe11 will write its results to the 
given file rather than to standard output. 


The -v option causes ispe11 to print its current version identification on the standard output and exit. If the switch is 
doubled, ispe11 will also print the options that it was compiled with. 











The -c, -e[1-4], and -p options of ispe11 are primarily intended for use by the munchlist shell script. T he -c switch causes a 
list of words to be read from the standard input. For each word, a list of possible root words and affixes will be written to the 
standard output. Some of the root words will be illegal and must be filtered from the output by other means; the munchlist 
script does this. Asan example, the command 


echo BOTHER ; ispell -c 

produces 

BOTHER BOTHE/R BOTH/R 

The -e switch is the reverse of -c; it expands affix flags to produce a list of words. For example, the command 
echo BOTH/R | ispell -e 

produces 

BOTH BOTHER 
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An optional expansion level can also be specified. A level of 1 (-e1) isthe same as -e alone A level of 2 causes the original 
root/affix combination to be prepended to the line 


BOTH/R BOTH BOTHER 


A lev of 3 causes multiple lines to be output, one for each generated word, with the original root/affix combination 
followed by the word it creates: 


BOTH/R BOTH 
BOTH/R BOTHER 


A level of 4 causes a floating-point number to be appended to each of the levd 3 lines, giving the ratio between the length of 
the root and the total length of all generated words including the root: 


BOTH/R BOTH 2.500000 
BOTH/R BOTHER 2.500000 


Finally, the -p flag causes the affix tables from the dictionary file to be dumped to standard output. 


Unless your system administrator has suppressed the feature to save space, ispel1 is aware of the correct capitalizations of 
words in the dictionary and in your personal dictionary. As well as recognizing words that must be capitalized (such as 
George) and words that must be all capitals (such asN ASA), it can also handle words with unusual capitalization (for 
example, IT -Corp or T eX ). If a word is capitalized incorrectly, the list of possibilities will include all acceptable capitaliza- 
tions. (M ore than one capitalization may be acceptable, for example, my dictionary lists both |T Corp and IT corp.) 


Normally, this feature will not cause you surprises, but there is onecircumstance you need to be aware of. If you use 1 to add 
a word to your dictionary that is at the beginning of a sentence (for example the first word of this paragraph if normally were 
not in the dictionary), it will be marked as “capitalization required.” A subsequent usage of this word without capitalization 
will be considered a misspdling by ispe11, and it will suggest the capitalized version. You must then compare the actual 
spellings by eye, and then type! to add the uncapitalized variant to your personal dictionary. You can avoid this problem by 
using u to add the original word, rather than 1. 


Therules for capitalization are as follows: 


1. Any word may appear in all capitals, as in headings. 

2. Any word that isin the dictionary in all lowercase form may appear either in lowercase or capitalized (as at the 
beginning of a sentence). 

3. Any word that has unusual capitalization (that is, it contains both cases and there is an uppercase character besides the 
first) must appear exactly asin the dictionary, except as permitted by rule 1. If the word is acceptable in all lowercase it 
must appear thus in a dictionary entry. 


buildhash 


The buildhash program builds hashed dictionary files for later use by ispe11. T heraw word list (with affix flags) is given in 
dict-file, and the affix flags are defined by atfix-file. The hashed output is written to hash-file. The formats of the two 
input files are described in ispe11(4). The -s (silent) option suppresses the usual status messages that are written to the 
standard error device. 





munchlist 


Themunchlist shell script is used to reduce the size of dictionary files, primarily personal dictionary files. It is also capable of 
combining dictionaries from various sources. T he given files are read (standard input if no arguments are given), reduced to 
a minimal set of roots and affixes that will match the same list of words, and written to standard output. 


Input for munchlist contains of raw words (such as those from your personal dictionary files) or root and affix combinations 
(probably generated in earlier munchlist runs). Each word or root/affix combination must be on a separate line. 


The -p (debug) option leaves tenporary files around under standard names instead of deleting them, so that the script can be 
debugged. W arning: This option can eat up an enormous amount of temporary file space. 


The -v (verbose) option causes progress messages to be reported to stderr So you won't get nervous that munchiist has hung. 
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If the -s (strip) option is specified, words that are in the specified hash-file are removed from the word list. T his can be 
useful with personal dictionaries. 


The -1 can be used to specify an alternate affix-file for munching dictionaries in languages other than English. 


The -c option can be used to convert dictionaries that were built with an older affix file, without risk of accidentally 
introducing unintended affix combinations into the dictionary. 


The -t option allows dictionaries to be converted to a canonical string-character format. T he suffix specified is looked up in 
the affix file (-1 switch) to determine the string-character format used for the input file, the output always uses the canonical 
string-character format. For example a dictionary collected from T eX source files might be converted to canonical format by 
specifying -T tex. 


The -w option is passed on to ispell. 


findaffix 


The findatfix shell script is an aid to writers of new language descriptions in choosing affixes. The given dictionary files 
(standard input if none are given) are examined for possible prefixes (-p switch) or suffixes (-s switch, the default). Each 
commonly occurring affix is presented along with a count of the number of times it appears and an estimate of the number 
of bytes that would be saved in a dictionary hash file if it were added to the language table. O nly affixes that generate legal 
roots (found in the original input) are listed. 


If the -c option is not given, the output lines are in the following format: 
strip/add/count/bytes 


whee strip is the string that should be stripped from a root word before adding the affix, add is the affix to be added, count 
is acount of the number of times that this strip/add combination appears, and bytes is an estimate of the number of bytes 
that might be saved in the raw dictionary file if this combination is added to the affix file. T he field separator in the output 
will be the tab character specified by the -t switch; the default is a slash (/). 


If the -c (clean output) option is given, the appearance of the output is made visually cleaner (but harder to post process) by 
changing it to 

-striptadd<tab>count<tab>bytes 

whe@e strip, add, count,and bytes areas before, and <tab> reoresents the ASCII tab character. 


The method used to generate possible affixes will also generate longer affixes which have common headers or trailers. For 
example, the two words moth and mother will generate not only the obvious substitution +er but also -h+her and -th+ther 
(and possibly even longer ones, depending on the value of min). To prevent cluttering the output with such affixes, any affix 
pair that shares a common header (or, for prefixes, trailer) string longer than e1im characters (default 1) will be suppressed. 
You may want to set e1im to a value greater than 1 if your language has string characters; usually, the need for this parameter 
will become obvious when you examine the output of your findaffix run. 


Normally, the affixes are sorted according to the estimate of bytes saved. T he -F switch may be used to cause the affixes to be 
sorted by frequency of appearance. 


To save output file space, affixes which occur fewer than 10 times are diminated; this limit may be changed with the -1 
switch. The -m switch specifies a maximum affix length (default 8). Affixes longer than this will not be reported. (T his saves 
on temporary disk space and makes the script run faster.) 


Affixes which generate stems shorter than three characters are suppressed. (A stem is the word after the strip string has been 
removed, and before the add string has been added.) T his reduces both the running time and the size of the output file. This 
limit may be changed with the -m switch. The minimum stem length should only be set to 1 if you havea lot of free time 
and disk space (in the range of many days and hundreds of megabytes). 


The findatfix script requires a nonblank field-separator character for internal use N ormally, this character is a slash (/), but 
if the slash appears as a character in the input word list, a different character can be specified with the -t switch. 


ispel1 dictionaries should be expanded before being fed to findatfix; in addition, characters that are not in theEnglish 
alphabet (if any) should be translated to lowercase. 


igpal, buildhash, munchlist, findaffix, tryaffix, icombine, ijoin 
tryaffix 


The tryatfix shal script is used to estimate the effectiveness of a proposed prefix (-p switch) or suffix (-s switch, the default) 
with a given expanded-file. Only one affix can be tried with each execution of tryaffix, although multiple arguments can be 
used to describe varying forms of the same affix flag (for example, theo flag for English can add ether p or Ep depending on 
whether atrailing E is already present). Each word in the expanded dictionary that ends (or begins) with the chosen suffix (or 
prefix) has that suffix (prefix) removed; the dictionary isthen searched for root words that match the stripped word. N or- 
mally, all matching roots are written to standard output, but if the -c (count) flag is given, only a statistical summary of the 
results is written. T he statistics given are a count of words the affix potentially applies to and an estimate of the number of 
dictionary bytes that a flag using the affix would save The estimate will be high if the flag generates words that are currently 
generated by other affix flags (for example in English, bathers can be generated by athe bath/x or bather/s). T he diction- 
ary file, expanded- file, must already be expanded (using the -e switch of ispe11) and sorted, and things will usually work 
best if uppercase has been folded to lower with tr. 


The affix arguments are things to be stripped from the dictionary file to produce trial roots: for English, con (prefix) and ing 
(suffix) are examples. T he addition parts of the argument are letters that would have been stripped off the root before adding 
the affix. For example, in English the affix ing normally stripse for words ending in that letter (for example, 1ike becomes 
liking), SO we might run 





tryaffix ing ingte 
to cover both cases. 


All of the shal scripts contain documentation as commentary at the beginning; sometimes these comments contain useful 
information beyond the scope of this manual page. 


It is possible to install ispe11 in such away as to only support ASCII range text if desired. 


icombine 


The icombine program is ahdper for munchlist. It reads alist of words in dictionary format (roots plus flags) from the 
standard input, and produces a reduced list of standard output that combines common roots found on adjacent entries. 
Identical roots that have differing flags will have their flags combined, and roots that have differing capitalizations will be 
combined in a way that only preservesimportant capitalization information. T he optional aff-file specifies a language file 
that defines the character sets used and the meanings of the various flags. T he -T switch can be used to sdect among 
alternative string character types by giving a dummy suffix that can be found in an altstringtype statement. 

ijoin 
The ijoin program is aramplanentation of join(1), which handles long lines and 8-bit characters correctly. The-s switch 
specifies that the sort(1) program used to prepare the input to ijoin uses signed comparisons on 8-bit characters; the -u 
switch specifies that sort(1) uses unsigned comparisons. All other options and behaviors of join(1) are duplicated as exactly 
as possible based on the manual page, except that ijoin will not handle newline asa field seoarator. See the join(1) manual 
page for more information. 


ENVIRONMENT 
DICTIONARY D efault dictionary to useif no -d flag is given 
WORDLIST Personal dictionary filename 
INCLUDE_STRING Codefor fileinclusion under the -a option 
TMPDIR Directory used for some of munchiist’s temporary files 
FILES 
!!LIBDIR!!/!!DEFHASH! ! H ashed dictionary (may be found in some other local directory, depending on the 
system) 
!!LIBDIR!!/!!DEFLANG! ! Affix-definition file for munchlist 


/usr/dict/web2 OF /usr/dict/words For the Lookup function (depending on theworps compilation option) 
User's private dictionary 
.ispell_hashfile D irectory-specific private dictionary 
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SEE ALSO 
spell(1), egrep(1), 100k(1), join(1), sort(1), sq(1L), tib(1L), ispe11(4L), english(4L) 


BUGS 
It takes several to many seconds for ispe1i to read in the hash table, depending on size. 


W hen all options are enabled, ispe11 may take several seconds to generate all the guesses at corrections for a misspelled word; 
on slower machines this time is long enough to be annoying. 


The hash table is stored as a quarter-megabyte (or larger) array, soa PD P-11 or 286 version does not seem likely. 
Ispell should understand more troff syntax, and deal more intelligently with contractions. 


Although small personal dictionaries are sorted before they are written out, the order of capitalizations of the same word is 
somewhat random. 


W hen the -x flag is specified, ispe11 will unlink any existing BAK file 
There are too many flags, and many of then have non-mnenonic names. 


munchlist does not deal very gracefully with dictionaries that contain nonword characters. Such characters ought to be 

dd eted from the dictionary with a warning message. findaffix and munchlist require trenendous amounts of temporary file 
space for large dictionaries. They do respect the tupp1r environment variable so this space can be redirected. H owever, a lot 
of the temporary space needed isfor sorting, so TuppiR is only a partial hdlp on systems with an uncooperative sort(1). 
(Cooperative is defined as accepting the undocumented -t switch). At its peak usage, munchlist takes 10 to 40 times the 
original dictionary’s size in kilobytes. (T he larger ratio is for dictionaries that already have heavy affix use, such asthe one 
distributed with ispei1). munchlist is also very Sow; munching anormal-sized dictionary (15K B roots, 45K B expanded 
words) takes around an hour on asmall workstation. (M ost of this timeis spent in sort(1), and munchlist can run much 
faster on machines that have amore modern sort that makes better use of the memory available to it.) findaffix is even 
worse the smallest English dictionary cannot be processed with this script in a mere 50KB of free space, and even after 
specifying switches to reduce the temporary space required, the script will run for more than 24 hours on a small worksta- 
tion. 


AUTHORS 


Pace W illisson (pace@mit-vax), 1983, based on the PD P-10 assembly version. T hat version was written by R. E. Gorin in 
1971, and later revised by W. E. M atson (1974) and W. B. Ackerman (1978). Collected, revised, and enhanced for the 
Usenet by Walt Buehring, 1987. T able-driven multilingual version by Geoff K uenning, 1987-88. Large dictionaries 
provided by Bob D evine (vianet!devine). A complete list of contributorsis too large to list here, but is distributed with the 
ispell sources in the file contributors. 


VERSION 


The version of ispe11 described by this manual page is! nternational | sod! version 3.1.00, O ctober 8, 1993. 


join 
join— Join lines of two files on a common fidd 


SYNOPSIS 


join [-a 1;2] [-v 1,2] [-e empty-string] [-o field-list...] [-t char] 
[-j[1!2] field] [-1 field] [-2 field] filel file2 
join {--help, --version} 


DESCRIPTION 


This manual page documents the GN U version of join. join prints to the standard output a line for each pair of input lines, 
oneeach from file1 andfile2, that have identical join fidds. Either filename (but not both) can be -, meaning the standard 


kill 


input. file1 and file2 should be already sorted in increasing order (not numerically) on the join fields; unless the -t option 
is given, they should be sorted ignoring blanks at the start of the line, as sort does when given the -b option. 


T he defaults are the following: T he join field isthefirst fidd in each line fidds in the input are separated by oneor more 
blanks, with leading blanks on theline ignored; fidds in the output are separated by a space; each output line consists of the 
join fidd, the remaining fidds from fil e1, then the remaining fidds from file2. 


OPTIONS 

-a file-number Print aline for each unpairable line in file fi1e-number (either 1 or 2), in addition to the normal 
output. 

-e string Replace enpty output fidds (those that are missing in the input) with string. 

-1, -j1 field Join on field tie1a (a positive integer) of file 1. 

-2, -j2 field Join on field field (a positive integer) of file 2. 

-j field Equivalent to -1 field -2 field. 

-o field-list... Construct each output line according to the format in field-1ist. Each dement in field-list 
consists of a file number (either 1 or 2), a period, and a fidd number (a positive integer). T he 
elements in the list are separated by commas or blanks. M ultiple field-1ist arguments can be 
given after a single -o option; the values of all lists given with -o are concatenated together. 

-t char Use character char asthe input and output fidd separator. 

-v file-number Print aline for each unpairable line in file fite-number (ther 1 or 2), instead of thenormal output. 


In addition, when GNU join isinvoked with exactly one argument, the following options are recognized: 
--help Print a usage message on standard output and exit successfully. 
--version Print version information on standard output, then exit successfully. 
GNU Tet Utilitie 


kill 
kill— T eminate a process 


SYNOPSIS 


kill [ -s signal | -p ] [-a]pid ... 
ki -l1 [ signal ] 


DESCRIPTION 

kil1 sends the specified signal to the specified process. If no signal is specified, the Term signal is sent. The Term signal will kill 
processes that do not catch this signal. For other processes, if may be necessary to use the KILL(9) signal because this signal 
cannot be caught. 


M ost modern shells have a built-in kill function. 








OPTIONS 
pid... Specify thelist of processes that ki11 should signal. Each pid can bea process |D, or a process name 
-s Specify the signal to send. The signal may be given asa signal name or number. 
-p Specify that ki11 should only print the process|!D (pid) of the named process, and should not send it a signal. 
-1 Print alist of signal names. These are found in /usr/include/linux/signal.h. 
SEE ALSO 


bash(1), tcesh(1), kil1(2), sigvec(2) 
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AUTHOR 
Taken from BSD 4.4. The ability to translate process names to process ids was added by Salvatore Valente 
(<svalente@mit.edu>), 


Linux Utilities, 14 October 1994 


killall 








all— Kill processes by name 
SYNOPSIS 
killall [-iv][-signal ] name ... 
killall [-1] 
DESCRIPTION 
killall sends a signal to all processes running any of the specified commands. If no signal nameis specified, s1aTERM is sent. 





Signals can be specified either by name (for example -HuP) or by number (for example, -1). Signal o (check if a process exists) 
can only be specified by numbe.. 


If the command name contains a slash (/), processes executing that particular file will be selected for killing, independent of 
their name 

killall returns anonzero return codeif no process has been killed for any of the listed commands. If at least one process has 
been killed for each command, killall returns zero. 


A killall process never kills itself (but may kill other killal1 processes). 


OPTIONS 
-i Interactively ask for confirmation of killing. 
-1 List all known signal names. 
-v Report if the signal was successfully sent. 
FILES 
/proc Location of the proc filesystem 
KNOWN BUGS 
Killing by file only works for executables that are kept open during execution; that is, impure executables can’t be killed this 
way. 
AUTHOR 
Werner Almesberger (almesber@di.epf1.ch) 
SEE ALSO 


kill(1), fuser(1), ps(1), ki11(2) 
Linux, 11 Octobe 1994 


ksyms 


ksyms— Shows the exported kernel symbols 


SYNOPSIS 


ksyms [-a][-h] [-m] 


DESCRIPTION 
ksyms shows information about all exported kernel symbols. T he format is 
address name [defining module] 
The describing header can be turned off with the option -h. 


Normally, only the symbols defined by the loaded modules are shown, but with the option -a, all exported symbols can be 
seen. 


The information can also be seen in /proc/ksyms. A shdl-script version ksyms.sh can be used to get the information from / 
proc/ksyms instead, but this program gets the symbol information directly from the kernel with a system call. 


With the option -m (stands for memory map), you can also see the starting address and the size of the allocated memory for 
every loaded module. 
SEE ALSO 


insmod(1), modprobe(1), depmod(1), rmmod(1), 1smod(1), modules(2) 


HISTORY 
The ksyms command was first conceived by Bjorn Ekwall (bjarn@blox.se). The -m option was inspired by David Hinds 
(dhinds@allegro.stanford. edu) 
BUGS 
Ksyms might have some, but they are wal hidden... 
Linux, 14 May 1995 


last 


last— Indicate last logins by user or terminal 


SYNOPSIS 


last [-number ][-f filename][-t tty][-h hostname][-i address ][-l][-y][name...] 


DESCRIPTION 


Last looks back in the wtmp file, which records all logins and logouts for information about a user, atdetype, or any group of 
users and teletypes. Arguments specify names of users or teletypes of interest. If multiple arguments are given, the informa- 
tion that applies to any of the arguments is printed. For example last root console would list all of root’s sessions as well as 
all sessions on the console terminal. Last displays the sessions of the specified users and tdetypes, most recent first, indicating 
the times at which the session began, the duration of the session, and the teletype that the session took place on. If the 
session is still continuing or was cut short by a reboot, 1ast so indicates. 


The pseudo-user reboot logs in at reboots of the systen. 
Last with no arguments displays a record of all logins and logouts, in reverse order. 


If 1ast isinterrupted, it indicates how far the search has progressed in wtmp. If interrupted with a quit signal, 1ast indicates 
how far the search has progressed so far, and the search continues. 


OPTIONS 
number Limit the number of entries displayed to that specified by number. 
-f filename Usefilename as thename of the accounting file instead of /var/1og/wtmp. 
-h host name List only logins from host name. 


-i IP address List only logins from IP address. 
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<1 List IP addresses of remote hosts instead of truncated hostnames. 
-t tty List only logins ontty. 
-y Also report year of dates. 

FILES 


/var/log/wtmp | Login database 


lbxproxy 


20 M arch 1992 


lbxproxy— LBX proxy server for the X W indow systen 


SYNOPSIS 


lbxproxy [:displaynumber ] [option ...] 


NOTE 


This manual page is not definitive or “official.” It is derived from information contained in the reaome file in the 1bx source 


DESCRIPTION 


lbxproxy isthe Low Bandwidth X pseudo-server. It runs on the remote side of low bandwidth, high-latency connections, 
such as sevial lines and wide area networks. It accepts connections from X clients at the remote end and forwards them to an 
X server at the local end. The LBX protocol used for the low bandwidth connection includes compression and optimizations 
designed to make effective use of the bandwidth available The current version of LBX isnot a standard of the X Consor- 
tium, and will not be compatible with the final version. The current version should be treated as an “alpha” or “prototype” 
for people interested in experimenting with it. 


OPTIONS 


lbxproxy accepts the following options: 


rdisplaynumber 


-ac 


-display display-number 


lbxproxy runs as the given displaynumber, which by default is a. A value different from 0 should be 
used if the host running lbxproxy has alocal X display. If multiple 1bxproxy servers or other X 
servers are to run simultaneously on a host, each must have a unique display number. (See the 
“Display N ames” section of the x(1) manual page to learn how to specify which display number 
clients should try to use) 

Disables host-based access control mechanisms. Enables access by any host, and permits any host to 
modify the access control list. U se with extreme caution. This option exists primarily for running 
test suites remotely. 

Sets the name of the X server display that 1bxproxy connects to. 


-help Prints a usage message. 
-I Causes all remaining command-line arguments to be ignored. 
-to seconds Sets default connection timeout in seconds. 

NETWORK CONNECTIONS 


lbxproxy supports client connections via most of the connection types supported by the X servers. (Refer to the xserver(1) 
manual page and hardware-specific X server manual pages for details.) N ote that in the current implementation some of the 
connections types have not ben implemented correctly. This mostly applies to Systen V. 


EXA 


MPLES 


To setup lbxproxy, start the X server as usual, and then start the proxy. The lbxproxy is a pseudo-server, so any clients that 
wish to useit need to adjust their prspLay. By default, the proxy will listen on <hostname>:1. This can be changed with the 


:displaynumber argument. 


If the proxy is to be running on a host named sharedhost, connecting to an LBX-capable X server on a desktop machine 
named mydesktop, you could use the following command to start the proxy (which would be known as display sharedhost:7): 


mydesktop% rlogin sharedhost 
sharedhost% lbxproxy -display mydesktop:0 :7 & 
sharedhost% xclient -display sharedhost:7 


If you ae running LBX over a Term connection between mydesktop and sharedhost, try something like this: 


mydesktop% trsh 

sharedhost% tredir -r 6008 6000 

sharedhost% lbxproxy -display sharedhost:8 :7 & 
sharedhost% xclient -display sharedhost:7 


SEE 


ALSO 


General information: x(1) 


Server-specific man pages: xserver(1), xdec(1), Xmact1(1), Xsun(1), xnest(1), Xvfb(1), xF86_Acce1(1), XF86_Mono(1), 
XF86_SVGA(1), xF86_VGA16(1), xFrees6(1) 


AUTHORS 


TheLBX team includes D aveLenke, D ale T onogai, K ath Packard, Jim Fulton from NCD, and Chris Kanterjiev from 
Xerox. 
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d— TheGNU linker 


SYNOPSIS 
d [ -o.I output ] .I objfile . .. .br .RB ["-A output ] objfile ... 
[-A architecture ][-b\ input-format ][-Bstatic ][-c\ commandfile ] 


[ -dj-dej-dp ] 

[ -defsym\ symbol = expression ][-e\ entry ][-F ][-F\ format ][- 
ormat\ input-format J[-g ][-G size ][--help ][-i ][-1l ar ][- 

L searchdir ][-M][-Map mapfile ][-m emulation ][-nj-N][- 


noinhibit-exec ][-oformat\ output-format ][-R\ filename ][-relax ] 


{ -r}-Ur][-S ][-s ][-sort-common][-T\ commandfile ][-Ttext\ 
extorg J][-Tdata\ dataorg ][-Tbss\ bssorg ][-t ][-u\ sym ][-V ][- 





v][--verbose ][--version ][-warn-common][-warn-once][-X ] 


[ -x ] 


DESCRIPTION 


1d combines a number of object and archive files, relocates their data, and ties up symbol references. Often the last step in 
building a new compiled program to run is acall to 14. 


1d accepts Linker Command Language files to provide explicit and total control over the linking process. This man page does 
not describe the command language; see the 1d entry in info, or the manual Ld: TheGNU Linker, for full details on the 
command language and on other aspects of theG N U linker. 


288 
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This version of 1d uses the general-purpose BFD libraries to operate on object files. This allows 1a to read, combine and 
write object files in many different formats, for example, COFF or a.out. Different formats may be linked together to 
produce any available kind of object file You can use objdump -i to get alist of formats supported on various architectures; 
see objdump(1). 


Aside from its flexibility, the GN U linker ismore hdpful than other linkers in providing diagnostic information. M any 
linkers abandon execution immediately upon encountering an error; whenever possible 1d continues executing, allowing 
you to identify other errors (or, in some cases, to get an output file in spite of the error). 


TheGNU linker 1d ismeant to cover a broad range of situations, and to be as compatible as possible with othe linkers. Asa 
result, you have many choices to control its behavior through the command line, and through environment variables. 


OPTIONS 


The plethora of command-line options may seam intimidating, but in actual practice few of them are used in any particular 
context. For instance, a frequent use of 1d isto link standard UNIX object files on astandard, supported UNIX systen. On 
such a system, thisline links afile hello.o : 


$ ld -o output /lib/crt®.o hello.o -1c 


This tells 14 to produce a file called output as the result of linking the file /1ib/crt@.o with hello.o and thelibrary libc.a, 
which will comefrom the standard search directories. 


The command-line options to 1d may be specified in any order, and may be repeated at will. For the most part, repeating an 
option with a different argument will either have no further effect or override prior occurrences (those further to the left on 
the command line) of an option. 


The exceptions— which may meaningfully be used more than once— are -A, -b (or its synonym -format), -defsym, -L, -1, -R, 
and -u. 


Thelist of object files to be linked together, shown as objfile, may follow, precede, or be mixed in with command-line 
options, except that an objfile argument may not be placed between an option flag and its argument. 


Usually the linker is invoked with at least one object file but other forms of binary input files can also be specified with -1, 
-R, and the script command language. If no binary input files at all are specified, thelinker does not produce any output, and 
issues the message No input files. 


Option arguments must ether follow the option letter without intervening whitespace or be given as separate arguments 
immediately following the option that requires then. 


-Aarchitecture In the current release of 1a, this option is useful only for the Intel 960 family of architec- 
tures. In that 1a configuration, the architecture argument is one of the two-letter names 
identifying members of the 960 family; the option specifies the desired output target and 
warns of any incompatible instructions in theinput files. It also modifies the linker’s search 
strategy for archive libraries to support the use of libraries specific to each particular 
architecture, by including in the search loop names suffixed with thestring identifying the 
architecture. 

For example, if your 1d command lineincluded -aca as well as -1try, thelinker would look 
(in its built-in search paths, and in any paths you specify with -L) for a library with the 
names 

try 

libtry.a 

tryca 


libtryca.a 


The first two possibilities would be considered in any event; the last two are due to the use 
of -ACA. 


Future rdeases of 1d may support similar functionality for other architecture families. 


E 


You can meaningfully use -a morethan onceon acommand line, if an architecture family 
allows combination of target architectures; each use will add another pair of name variants 
to search for when -1 specifies a library. 

-b input-format Specify the binary format for input object files that follow this option on the command line 
You don’t usually need to specify this, asi is configured to expect as a default input format 
the most usual format on each machine. i nput- format isatext string, thename of a partic- 
ular format supported by the BFD libraries. 

-format input-format 

has the same effect, as does the script command TarceT. 

You may want to use this option if you are linking files with an unusual binary format. You 
can also use -b to switch formats explicitly (when linking object files of different formats), 
by including 

-b input- format 

before each group of object files in a particular format. 

The default format is taken from the environment variable anuTarGeT. You can also define 
the input format from a script, using the command TarcET. 


-Bstatic This flag is accepted for command-line compatibility with the SunOS linker, but has no 
effect on 1d. 
-c commandfile Directs 1a to read link commands from the file commandfile. T hese commands will 


completely override 1a’s default link format (rather than adding to it); commandfile must 
specify everything necessary to describe the target format. 

You may also include a script of link commands directly in the command line by bracketing 
it between ¢ and } characters. 


-d, -de, -dp T hese three options are equivalent; multiple forms are supported for compatibility with 
othe linkers. U se any of them to make 14 assign space to common symbols even if a 
relocatable output file is specified (-r). The script command FoRCE_COMMON ALLOCATION has 
the same effect. 

-defsym symbol = expression Create a global symbol in the output file containing the absolute address given by 
expression. YOUmay use this option as many times as necessary to define multiple symbols 
in thecommand line A limited form of arithmetic is supported for theexpression in this 
context; you may give ahexadecimal constant or the name of an existing symbol, or use + 
and - to add or subtract hexadecimal constants or symbols. If you need more daborate 
expressions, consider using the linker command language from a script. 


-e entry Useentry asthe explicit symbol for beginning execution of your program, rather than the 
default entry point. 
-F, -Fformat Some older linkers used this option throughout a compilation toolchain for specifying 


object-file format for both input and output object files. 1a’s mechanisms (the -b or -format 
options for input files, the TarceT command in linker scripts for output files, the cuuTARGET 
environment variable) are more flexible, but it accepts (and ignores) the -F option flag for 
compatibility with scripts written to call the old linker. 


-format input-format Synonym for -b input-format. 

-g Accepted, but ignored; provided for compatibility with other tools. 

-G size Se the maximum size of objects to be optimized using the GP register tosize under MIPS 
ECOFF. Ignored for other object file formats. 

--help Print a summary of the command-line options on the standard output and exit. This option 


and --version begin with two hyphens instead of one for compatibility with other GN U 
programs. T he other options start with only one hyphen for compatibility with other 
linkers. 


-i Perform an incremental link (same as option -r). 
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-lar 


-Lsearchdir 
-M 

-Map mapfile 
-m emulation 


-n 


-noinhibit-exec 


-O output output 


-oformat output-format 


-R filename file 


-relax 


-S 
-S 


-sort-common 


Add an archivefile ar to the list of files to link. This option may be used any number of 
times. 1d will search its path list for occurrences of 1ib ar .a for every ar specified. 

This command adds path searchdir to thelist of paths that 1a will search for archive 
libraries. You may use this option any number of times. 

The default set of paths searched (without being specified with -L) depends on what 
emulation mode id isusing, and in some cases also on how it was configured. T he paths 
can also be specified in alink script with the searcH_pIR Command. 

Print (to the standard output file) a link map— diagnostic in-formation about where 
symbols are mapped by 14, and information on global common storage allocation. 

Print to thefile maptile alink map— diagnostic information about where symbols are 
mapped by 14, and information on global common storage allocation. 

Emulate the emu! ation linker. You can list the available emulations with the - - verbose 
option. This option overrides the compiled-in default, which is the system for which you 
configured 14. 

Specifies readable and writable text and data sections. If the output format supports 
UNIX-style magic numbers, the output is marked as omaaic. 

W hen you use the -n option, the linker does not page-align the data segment. 

Sets the text segment to be read-only, and nwaarc is written if possible 

Normally, the linker will not produce an output file if it encounters errors during the link 
process. With this flag, you can specify that you wish the output file retained even after 
nonfatal errors. 

output isaname for the program produced by 1a; if this option isnot specified, thename 
a.out is used by default. The script command output can also specify the output filaaame 
Specify the binary format for the output object file. You don’t usually need to specify this, 
as 1d is configured to produce as a default output format the most usual format on each 
machine. out put-format isatext string, the name of a particular format supported by the 
BFD libraries. The script command output_FormaT can also specify the output format, but 
this option overrides it. 

Read symbol names and their addresses from fi! ename, but do not relocate it or include it in 
the output. This allows your output file to refer symbolically to absolute locations of 
memory defined in othe programs. 

An option with machine-dependent effects. C urrently this option is only supported on the 
H 8/300. 

On someplatforms, use this option to perform global optimizations that become possible 
when the linker resolves addressing in your program, such as rdaxing address modes and 
synthesizing new instructions in the output object file. 

On platforms whee this is not supported, -relax is accepted, but hasno effect. 

Generates relocatable output, that is, an output file that can in turn serve as input to 1a. 
This is often called partial linking. As aside effect, in environments that support standard 
UNIX magic numbers, this option also sets the output file's magic number to omactc. If this 
option is not specified, an absolute file is produced. When linking C++ programs, this 
option will not resolve references to constructors, -ur isan alternative 

This option does the same as -i. 

O mits debugger symbol information (but not all symbols) from the output file. 

O mits all symbol information from the output file 

Normally, when 1a places the global common symbols in the appropriate output sections, it 
sorts them by size. First come all the one-byte symbols, then all the two bytes, then all the 
four bytes, and then everything dse Thisis to prevent gaps between symbols due to 
alignment constraints. T his option disables that sorting. 


-&E 


-Tbss org, -Tdata org, Useorg as the starting address for— respectively— the bss, data, or the text segment of the 
-Ttext org output file. textorg must be a hexadecimal integer. 

-T commandfile, -Tcommandfile Equivalentto -c commandfile; supported for compatibility with other tools. 

-t Prints names of input files as1d processes them. 

-u sym Forces sym to be entered in the output file as an undefined symbol. This may, for example, 


trigger linking of additional modules from standard libraries. -u may be repeated with 
different option arguments to enter additional undefined symbols. 

-Ur For anything other than C ++ programs, this option is equivalent to -r : it generates 
relocatable output, that is, an output file that can in turn serve asinput to 1d. When linking 
C++programs, -ur will resolve references to constructors, unlike -r. 





--verbose Display the version number for 1a and list the supported enulations. Display which input 
files can and can not be opened. 

-v, -V Display the version number for 1a. 

--version Display the version number for 1a and exit. 

-warn-common Warn when acommon symbol is combined with another common symbol or with a symbol 


definition. UN IX linkers allow this somewhat sloppy practice, but linkers on some other 
operating systems do not. This option allows you to find potential problems from 
combining global symbols. 


-warn-once Only warn once for each undefined symbol, rather than once per module that refers to it. 

-X If -s or -s is also specified, dd ete only local symbols beginning with L. 

-x If -s or -s is also specified, ddete all local symbols, not just those beginning with L. 
ENVIRONMENT 


You can change the behavior of 14 with the environment variable GnuTaRGET. 


GNUTARGET determines the input-file object format if you don’t use -b (or its synonym -format). I ts value should be one of the 
BFD names for an input format. If there isno anutarGeT in the environment, 1d uses the natural format of the host. If 
GNUTAR-GET is set to default, then BFD attempts to discover theinput format by examining binary input files, this method 
often succeeds, but there are potential ambiguities, since there is no method of ensuring that the magic number used to flag 
object-file formats is unique. H owever, the configuration procedure for BFD on each system places the conventional format 
for that system first in the search-list, so ambiguities are resolved in favor of convention. 


SEE ALSO 
objdump(1); 1d and binutils entriesin info 
Ld: TheGNU Linker, Steve Chamberlain and Roland Pesch; TheGNU Binary U tilities Roland H. Pesch. 


COPYING 
Copyright © 1991, 1992 Free Software F oundation, Inc. 


Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this 
permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus upport, 17 August 1992 
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lispmtopgm 
lispmtopgm— Convert a Lisp M achine bitmap fileinto PGM format 


SYNOPSIS 


lispmtopgm [lispmfile] 


DESCRIPTION 
lispmtopgm reads a Lisp machine bitmap as input and produces a portable graymap as output. 
This is the file format written by the tv:write-bit-array-file function on T| Explorer and Symbolics Lisp machines. 
M ultiplane bitmaps on Lisp machines are color; but the 1ispm image file format does not include a colormap, so it must be 
treated as a graymap instead. T his is unfortunate. 
SEE ALSO 


pgmtolispm(1), pgm(5) 


BUGS 


The 1ispm bitmap file format is a bit quirky; U sually the image in the file has its width rounded up to the next higher 
multiple of 32, but not always. If the width is not a multiple of 32, we don’t deal with it properly, but because of the 1ispm 
microcode, such arrays are probably not image data anyway. 


Also, the 1ispm code for saving bitmaps has a bug, in that if you are writing a bitmap that is not moas2 across, the file may be 
up to seven bits too short. T hey round down instead of up, and we don’t handle this bug gracefully. 


Nocolor. 


AUTHOR 
Copyright© 1991 by J amie Zawinski and J ef Poskanzer. 
6 M arch 1990 


1kbib 


1kbib— Search bibliographic databases 


SYNOPSIS 


lkbib [ -v ][-ifields ][-pfilename ][-tn ] key ... 


DESCRIPTION 


lkbib searches bibliographic databases for references that contain the keyskey... and prints any references found on the 
standard output. 1kbib will search any databases given by -p options, and then a default database The default database is 
taken from the REFER environment variable if it is set, otherwise it is 


/usr/dict/papers/Ind. 


For each database filename to be searched, if an index filename.i created by gindxbib(1) exists, then it will be searched 
instead; each index can cover multiple databases. 


OPTIONS 
-v Print the version number. 
-pfil ename Search filename. Multiple -p options can be used. 
-istring W hen searching files for which no index exists, ignore the contents of fields whose names arein string. 


-tn Only requirethefirstn characters of keys to be given. Initiallyn is6. 


, 


ENVIRONMENT 


REFER D efault database 


FILES 
/usr/dict/papers/Ind D efault database to be used if the REFER environment variable is not set. 
filename.i Index files. 


SEE ALSO 


grefer(1), glookbib(1), gindxbib(1) 
Groff Veron 1.09, 6 August 1992 


ln 


in— M ake links between files 


SYNOPSIS 


In [options] source [dest] 
In [options] source... directory 


O ptions: 


[-bdfinsvF] [-S backup-suffix] [-V {numbered,existing,simple}] 
[--version-control={numbered,existing,simple}] [--backup] [--directory] 
[--force] [--interactive] [--no-dereference] [--symbolic] [--verbose] 
[--suffix=backup-suffix] [--help] [--version] 


DESCRIPTION 


This manual page documents the GN U version of in. If the last argument names an existing directory, 1n links each other 
given file into a file with the same name in that directory. If only one file is given, it links that file into the current directory. 
O therwise, if only two files are given, it links the first onto the second. It is an error if the last argument isnot a directory 
and more than two files are given. It makes hard links by default. By default, it does not renove existing files. 


OPTIONS 

-b, --backup M ake backups of files that are about to be removed. 

-d, -F, --directory Allow the superuser to make hard links to directories. 

-f, --force Remove existing destination files. 

-i, --interactive Prompt whether to remove existing destination files. 

-n, --no-dereference When the specified destination is a symbolic link to adirectory, attempt to replace the 
symbolic link rather than dereferencing it to create a link in the directory to which it points. 
This option is most useful in conjunction with - -force. 

-s, --symbolic M ake symbolic links instead of hard links. T his option produces an error message on 
systems that do not support symbolic links. 

-v, --verbose Print the name of each file before linking it. 

--help Print a usage message on standard output and exit successfully. 

--version Print version information on standard output then exit successfully. 


-S, --suffix backup-suffix The suffix used for making simple backup files can be set with the sImPLE_BACKUP_SUFFIX 
environment variable, which can be overridden by this option. If neither of thoseis given, 
the default is ~, as it isin Emacs. 
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-V, --version-control The type of backups made can be set with the versIon_conTROL environment variable, which 
{numbered , existing, simple} can be overridden by this option. If verston_controL isnot set and this option is not given, 
the default backup type is existing. The value of the verSIon_CoNTROL environment variable 
and the argument to this option are like the GN U Emacs version-control variable they 
also recognize synonyms that are more descriptive. The valid values (unique abbreviations 
are accepted) are the following: 
t OF numbered Always make numbered backups. 
nil Of existing Makenumbered backups of files that already havethem, simple 
backups of the others. 


never Of simple Alwaysmake simple backups. 





GNU FileUtilitie 


Indir 


Indir— Create a shadow directory of symbolic links to another directory tree 


SYNOPSIS 


Indir fromdir [todir] 


DESCRIPTION 


Indir makes a shadow copy todir of a directory tree fromdir, except that the shadow is not populated with real files but 
instead with symbolic links pointing at the real files in the fromair directory tree. This is usually useful for maintaining 
source code for different machine architectures. You create a shadow directory containing links to the real source which you 
will have usually N FS mounted from a machine of a different architecture, and then recompile it. T he object files will bein 
the shadow directory, while the source files in the shadow directory are just symlinks to the real files. 


This has the advantage that if you update the source, you need not propagate the change to the other architectures by hand 
because all source in shadow directories are symlinks to the real thing: J ust cd to the shadow directory and recompile away. 


The todir argument is optional and defaults to the current directory. The fromdir argument may be rdative (for example, 
../src) and is relative to todir (not the current directory). 


N ote that rcs, sccs, and cvs.adm directories are not shadowed. 
If you add files, simply run indir again. D eleting files isa more painful problem; the symlinkswill just point into never- 
neverland. 
BUGS 
patch gets upset if it cannot change the files. You should never run patch from ashadow directory anyway. 
You need to use something like this: 
find todir -type 1 -print | xargs rm 
to clear out all files before you can rdink (if fromdir moved, for instance). Something like this: 
find . \! -type d -print 
will find all files that are not directories. 
X Verson 11 Release 6 


locate 


locate— List files in databases that match a pattern 


SYNOPSIS 


locate [-d path] [--database=path] [--version] [--help] pattern... 


DESCRIPTION 


This manual page documents the GN U version of locate. For each given pattern, locate searches one or more databases of 
filenames and displays the filenames that contain the pattern. Patterns can contain shell-style meta characters: «, 2, and []. 
The meta characters do not treat / or . specially. Therefore, a pattern foo*bar can match a filename that contains foo3/bar, 
and a pattern *duck* can match a filename that contains lake/.ducky. Patterns that contain meta characters should be quoted 
to protect them from expansion by the shell. 


If a pattern is a plain string— it contains no meta characters— locate displays all filavames in the database that contain that 
string anywhere If a pattern does contain meta characters, locate only displays filenames that match the pattern exactly. Asa 
result, patterns that contain meta characters should usually begin with a * and will most often end with one as well. The 
exceptions are patterns that are intended to explicitly match the beginning or end of a filename. 


The filename databases contain lists of files that were on the system when the databases were last updated. T he system 
administrator can choose the filename of the default database, the frequency with which the databases are updated, and the 
directories for which they contain entries; see updatedb(1L). 


OPTIONS 
-d path, --database=path Instead of searching the default filename database, search the filename databases in path, 
which is a colon-separated list of database filevames. You can also use the environment 
variable LocaTe_PATH to set thelist of database files to search. The option overrides the 
environment variable if both are used. 
The filename database format changed starting with GN U find and locate version 4.0 to 
allow machines with different byte orderings to share the databases. T his version of locate 
can automatically recognize and read databases produced for older versions of GNU locate 
or UNIX versionsof locate or find. 
--help Print asummary of the options to locate and exit. 
--version Print the version number of locate and exit. 
ENVIRONMENT 
LOCATE_PATH Colon-separated list of databases to search 
SEE ALSO 


find(1L), locatedb(5L), updatedb(1L), xargs(1L), Finding Files(onlinein info, or printed) 


logger 


logger— M ake entriesin the system log 


SYNOPSIS 


logger [-is] [-f file] [-p pri] [-t tag] [message ...] 


DESCRIPTION 


logger provides a shell command interface to the sys1og(3) systan log module. 
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OPTIONS 
-i Log the process|ID of thelogger process with each line 
-8 Log the message to standard error, as well as the system log. 
-f file Log thespecified file. 
-p pri Enter the message with the specified priority. T he priority may be specified numerically or aS a facility. level 


pair. For example, -p 1ocal3. info logs the message(s) as informational levd in the local3 facility. The default is 
user.notice. 


-t tag M ark every line in the log with the specified tag. 
message | Writethe message to log; if not specified, and the -f flag is not provided, standard input is logged. 


The logger utility exits @ on success, and > if an error occurs. 
EXAMPLE 


logger system rebooted: 
logger -p local@.notice -t HOSTIDM -f /dev/idmc 


SEE ALSO 
syslog(3), syslogd(8) 
STANDARDS 
The logger command is expected to be compatible with IEEE Std 1003.2 (POSIX). 
BSD 4.3, 6 June1993 


login 


ogin— Sign on 


SYNOPSIS 

ogin [ name ] 
ogin -p 

ogin -h hostname 
ogin -f name 


DESCRIPTION 


ogin is used when signing on to asystem. It can also be used to switch from one user to another at any time (M ost modern 
shells have support for this feature built into then, however.) 





If an argument is not given, login prompts for the username 


If the user is not root, and if /etc/nologin exists, the contents of this file are printed to the screen, and the login is tami- 
nated. T his is typically used to prevent logins when the system is being taken down. 


If the user is root, then the login must be occurring on atty listed in /etc/securetty. Failures will be logged with the sysi1og 
facility. 

After these conditions are checked, the password will be requested and checked (if a password is required for this username). 
Ten attempts are allowed before login dies, but after the first three, the response starts to get very slow. Login failures are 
reported via the syslog facility. This facility is also used to report any successful root logins. 


If the file .nushlogin exists, then a quiet login is performed (this disables the checking of the checking of mail and the 
printing of the last login time and message of the day). O therwise, if /var/1og/lastlog exists, the last login time is printed 
(and the current login is recorded). 


look 297 


Random administrative things, such as setting the UID and GID of the tty, are peformed. The Term environment variable is 
preserved, if it exists; other environment variables are preserved if the -p option is used. Then the Home, PATH, SHELL, TERM, 
MAIL, and LOGNAME environment variables are set. PATH defaults to /usr/local/bin:/bin:/usr/bin:. for normal users, and to / 
sbin: /bin: /usr/sbin: /usr/bin for root. Last, if thisisnot a quiet login, the message of the day is printed and the file with the 
user’Snamein /usr/spool/mail will be checked, and a message printed if it has nonzero length. 


Theuser’s shell is then started. If no shall is specified for the user in /etc/passwd, then /bin/sh is used. If thereis no directory 
specified in /etc/passwd, then / is used. (The home directory is checked for the .hushlogin file described earlier.) 


OPTIONS 


-p Used by getty(8) to teal login not to destroy the nvironment. 


-f Used to skip a second login authentication. This specifically does not work for root, and does not appear to work 
wal under Linux. 


-h Used by other servers (such as te1neta(8)) to pass thename of theremote host to login so that it may be placed in 
utmp and wtmp. Only the superuser may use this option. 


FILES 
/var/run/utmp 
/var/log/wtmp 
/var/log/lastlog 
/usr/spool/mail/* 
/etc/motd 
/etc/passwd 
/etc/nologin 
/etc/usertty 
-hushlogin 


SEE ALSO 


init(8), getty(8), mail(1), passwd(1), passwa(5), environ(7), shutdown(8) 
BUGS 
Linux, unlike other Draconian operating systems, does not check quotas. 
Theundocumented BSD -r option is not supported. T hismay be required by some riogind(8) programs. 


AUTHOR 


Derived from BSD login 5.40 (M ay 9, 1989) by M ichad Glad (gladedaimi.dk) for H P-UX Ported to Linux 0.12: Peter 
O rbaek (poe@daimi.aau.dk). 


Linux 0.99, 1 February 1993 


look 


look— Display lines beginning with a given string 
SYNOPSIS 


look [-dfa] [-t termchar] string [file] 


DESCRIPTION 


The look utility displays any linesin file that contain string aS a prefix. AS look performs a binary search, the linesin file 
must be sorted. 
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If file is not specified, the file /usr/dict/words is used, only aphanumeric characters are compared, and the case of alphabetic 
characters is ignored. 


OPTIONS 
-d Dictionary character set and order; that is, only alphanumeric characters are compared. 
-f Ignore the case of alphabetic characters. 
-a Use the alternate dictionary /usr/dict/web2. 
=t Specify a string termination character; that is, only the characters in string up to and including the first 


occurrence of termchar are compared. 


The look utility exits @ if one or more lines were found and displayed, 1 if no lines were found, and >1 if an error occurred. 


FILES 


/usr/dict/words Thedictionary 
/usr/dict/web2 Thealternate dictionary 


SEE ALSO 
grep(1), sort(1) 


COMPATIBILITY 


The original manual page stated that tabs and blank characters participated in comparisons when the -d option was specified. 
This was incorrect and the current man page matches the historic implementation. 


HISTORY 
look appeared in version 7 AT&T UNIX. 
14 June1993 


Lpq 


1pq— Spool queue examination program 


SYNOPSIS 


1lpq [-1] [-P printer] [job # ...] [user ...] 


DESCRIPTION 


1pq examines the spooling area used by 1pd(8) for printing files on theline printer, and reports the status of the specified jobs 
or all jobs associated with auser. 1pq invoked without any arguments reports on any jobs currently in the queue. 


OPTIONS 
-P Specify a particular printer; otherwise the default line printer is used (or the value of the printer variable in the 
environment). All other arguments supplied are interpreted as usernames or job numbers to filter out only those 
jobs of interest. 
-1 Information about each of the files comprising the job entry is printed. Normally, only as much information as 
will fit on one line is displayed. 


For each job submitted— in other words, each time 1pr(1) isinvoked— 1pq reports the user’s name, current rank in the 
queue, thenames of files comprising the job, the job identifie (a number that may be supplied to 1prm(1) for removing a 
specific job), and the total size in bytes. J ob ordering is dependent on the algorithm used to scan the spooling directory and is 
supposed to be FIFO (First in First O ut). Filenames comprising a job may be unavailable (when 1pr(1) is used asasink ina 
pipdine) in which case the file is indicated as (standard input). 


If 1pq warns that there isno daemon present (due to some malfunction, for example), the 1pc(8) command can be used to 
restart the printer daemon. 


ENVIRONMENT 
If the following environment variable exists, it is used by 1pq: 
PRINTER Specifies an alternate default printer 


FILES 
/etc/printcap To determine printer characteristics 
/var/spool/* The spooling directory, as determined from printcap 
/var/spool/*/cf* Control files specifying jobs 
Pa/var/spool/*/lock The lock fileto obtain the currently active job 
/usr/share/misc/termcap For manipulating the screen for repeated display 

SEE ALSO 
lpr(1), Lprm(1), 1pce(8), 1pa(8) 

HISTORY 
lpq appeared in BSD 3. 

BUGS 


Due to the dynamic nature of the information in the spooling directory, 1pq may report unreliably. O utput formatting is 
sensitive to the line length of the terminal; this can result in widdy spaced columns. 


DIAGNOSTICS 


Unable to open various files. T he lock file is malformed. Garbage files when there is no daemon active, but filesin the 
spooling directory. 


BSD 4.2,9 May1991 


lpr 


ipr— Offline print 


SYNOPSIS 
lpr [-P printer] [-# num] [-C class] [-J job] [-T title] [-U user] 
[-i [numcols]] [-1234 font] [-w num] [-cdfghlnmprstv] [name ...] 
DESCRIPTION 


lpr uses a spooling daemon to print the named files when facilities become available. If no names appear, the standard input 
is assumed. 


The following single letter options are used to notify the line printer spooler that the files are not standard text files. The 
spooling daemon will use the appropriate filters to print the data accordingly. 


-c The files are assumed to contain data produced by cifplot(1). 

-d The files are assumed to contain data from T eX (DV! format from Stanford). 

-f Usea filter that interprets the first character of each line as astandard FORTRAN carriage control character. 

-g The files are assumed to contain standard plot data as produced by the plot routines. (See also plot for the filters 


used by the printer spooler.) 
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Use a filter that allows control characters to be printed and suppresses page breaks. 

The files are assumed to contain data from ditroff (deviceindependent troff). 

Use pr(1) to format the files (equivalent to print). 

The files are assumed to contain data from trof#(1) (cat phototypesetter commands). 
The files are assumed to contain a raster image for devices like the Benson Varian. 


T hese options apply to the handling of the print job: 


Force output to a specific printer. N ormally, the default printer is used (site dependent), or the value of the 
environment variable PRINTER is used. 


Suppress the printing of the burst page. 

Send mail upon completion. 

Remove the file upon completion of spooling or upon completion of printing (with the -s option). 

Use symbolic links. U sually, files are copied to the spool directory. The -s option will use symlink(2) to link data 


files rather than trying to copy them so large files can be printed. T his means the files should not be modified or 
removed until they have been printed. 


The remaining options apply to copies, the page display, and headers: 


-# num 


1234 font 


The quantity num isthe number of copies desired of each file named. For example, 

lpr -#3 foo.c bar.c more.c 

would result in three copies of the file foo.c, followed by three copies of the file bar.c, and so on. On the 
othe hand, 

cat foo.c bar.c more.c | lpr -#3 

will give three copies of the concatenation of the files. O ften asite will disable this feature to encourage use 
of a photocopier instead. 


Specifies a font to be mounted on font position i . The daemon will construct a .railmag file referencing 
the font pathname 


-C Ar class J ob classification to use on the burst page. For example 


lpr -C EECS foo.c 


causes the system name— the name returned by hostname(1)— to be replaced on the burst page by EECS, 
and the file foo.c to be printed. 


-J Ar job Job nameto print on the burst page. N ormally, the first file’s name is used. 

-T Ar title Title name for pr(1), instead of the fileaame 

-U user Username to print on the burst page, also for accounting purposes. This option is only honored if the real 
user ID is daemon (or that specified in the printcap file instead of daemon), and is intended for those 
instances where print filters wish to requeue jobs. 

-i numcols The output is indented. If the next argument is numeric numcols, it isused as the number of blanks to be 


printed before each line otherwise, eight characters are printed. 


-w Ns Ar num U ses num asthe page width for pr(1). 


ENVIRONMENT 


If the following environment variable exists, it is used by 1pr: 


PRINTER Specifies an alternate default printer 

FILES 
etc/passwd Personal identification. 
/etc/printcap Printer capabilities database. 
/usr/sbin/1pd* Line printer daemons. 
/var/spool/output /* Directories used for spooling. 


/var/spool/output/*/ct* Daemon control files. 
/var/spool/output/*/df* D ata files specified in cf files. 
/var/spool/output/*/tf* Temporary copies of cf files. 
SEE ALSO 
1pq(1), lprm(1), pr(1), symlink(2), printcap(5), 1pc(8), 1pd(8) 
HISTORY 
The 1pr command appeared in BSD 3. 
DIAGNOSTICS 


If you try to spool too large a file it will be truncated. 1pr will object to printing binary files. If auser other than root prints a 
file and spooling is disabled, 1pr will print a message saying so and will not put jobs in the queue. If a connection to 1pd(1) 
on the local machine cannot be made, 1pr will say that the daanon cannot be started. Diagnostics may be printed in the 
daemon’s log file regarding missing spool files by 1pa(1). 

BUGS 


Fonts for troff(1) and TeX reside on the host with the printer. It is currently not possible to use local font libraries. 
BSD 4, 24 July1991 


lprm 


lprm— Remove jobs from the line printer spooling queue 


SYNOPSIS 


Iprm [-P printer] [- job # ...] [user ...] 


DESCRIPTION 
lprm will renove ajob, or jobs, from aprinter’s spool queue. Since the spooling directory is protected from users, using 1prm 
is normally the only method by which a user may removea job. The owner of ajob is determined by the use’’s login name 
and hostname on the machine where the 1pr(1) command was invoked. 
O ptions and arguments: 


-P printer Specify the queue associated with a specific printer; otherwise, the default printer is used. 


If asingle - is given, 1prm will removeall jobs that a user owns. If the superuser employs this flag, the spool 
queue will be enptied entirely. 


user Causes 1prm to attempt to remove any jobs queued bdonging to that user (or users). Thisform of invoking 
iprm is useful only to the superuser. 
job # A user may dequeue an individual job by specifying its job number. This number may be obtained from 
the 1pq(1) program. For example 
Ipq - -l 
1st:ken [job#013ucbarpa] 
(standard input) 100 bytes 
Iprm 13 


If neither arguments nor options are given, 1prm will delete the currently active job if it is owned by the user who invoked 
lprn. 


lprm announces the names of any files it removes and is silent if there are no jobs in the queue that match the request list. 


iprm will kill off an active daemon, if necessary, before removing any spooling files. If a daemon is killed, anew oneis 
automatically restarted upon completion of file removals. 
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ENVIRONMENT 
If the following environment variable exists, it is utilized by 1prm: 


PRINTER If the environment variable printer exists, and a printer has not been specified with the -P option, the default 
printer is assumed from PRINTER. 


FILES 
/etc/printcap Printer characteristics file 
/var/spool/* Spooling directories 
/var/spool/*/ lock Lock file used to obtain the pid of the current daanon and the job number of the currently active 
job 
SEE ALSO 
Ipr(1), 1pq(1), 1pd(8) 
DIAGNOSTICS 
“Permission denied” if the user tries to remove files other than his own. 
BUGS 
Because there are race conditions possiblein the update of the lock file, thecurrently active job may be incorrectly identified. 
HISTORY 


The 1prm command appeared in BSD 3.0. 
BSD 4.2,9 May1991 


lIptest 


lptest— Generate line printer ripple pattern 


SYNOPSIS 


Iptest [length] [count] 


DESCRIPTION 


lptest writes the traditional “ripple test” pattern on standard output. In 96 lines, this pattern will print all 96 printable 
ASCII characters in each position. Although originally created to test printers, it is quite useful for testing terminals, driving 
terminal ports for debugging purposes, or any other task where a quick supply of random data is needed. 


The length argument specifies the output line length if the default length of 79 is inappropriate. 
The count argument specifies the number of output lines to be generated if the default count of 200 is inappropriate. N ote 
that if count isto be specified, 1ength must also be specified. 
HISTORY 
lptest appeared in BSD 4.3. 


BSD 4.3, 9 May1991 


Is, dir, vdir 


ls, dir, vdir 


ls, dir, vdir— List contents of directories 


SYNOPSIS 


1s [-abcdfgik1lmnpqrstuxABCFGLNQRSUX1] [-w cols] [-T cols] [-I pattern] [--all] 
[--escape] [--directory] [--inode] [--kilobytes] [--numeric-uid-gid] [-no-group] 
[--hide-control-chars] [--reverse] [--size] [--width=cols] [--tabsize=cols] 
[--almost-all] [--ignore-backups] [--classify] [--file-type] [--full-time] 
[--ignore=pattern] [--dereference] [--literal] [--quote-name] [--recursive] 

[ -sort={none, time, size, extension}] [--format={long, verbose, commas, 
across, vertical, single-column}] [--time={atime, access, use, ctime, status}] 
[--help] [--version] [name...] 


DESCRIPTION 


This manual page documents the GN U version of 1s. dir and vdir are versions of 1s with different default output formats. 
T hese programs list each given fileor directory name Directory contents are sorted alphabetically. For 1s, files are by default 
listed in columns, sorted vertically, if the standard output isa terminal; otherwise, they are listed one pe line For dir, files 
are by default listed in columns, sorted vertically. For vair, files are by default listed in long format. 





OPTIONS 

-a, --all List all files in directories, including all files that start with a period (.). 

-b, --escape Quote nongraphic characters in filenames using alphabetic and octal backslash sequences 
like those used in C. 

-c, --time=ctime, Sort directory contents according to the files’ status change time instead of the modification 

--time=status time. If the long listing format is being used, print the status change time instead of the 
modification time 

-d, --directory List directories like other files, rather than listing thar contents. 

-f Do not sort directory contents; list than in whatever order they are stored on the disk. This 
is the sameas enabling -a and -u and disabling -1, -s, and -t. 

--full-time List times in full, rather than using the standard abbreviation heuristics. 

-g Ignored; for UNIX compatibility. 

-i, --inode Print the index number of each file to the left of the filename. 

-k, --kilobytes If file sizes are being listed, print them in kilobytes. T his overrides the environment variable 
POSIXLY_CORRECT. 

-1, --format=long, In addition to the name of each file, print the file type permissions, number of hard links, 

--format=verbose owner name, group name, sizein bytes, and timestamp (the modification time unless other 
times are selected). For files with a time that is more than six months old or more than one 
hour into the future the timestamp contains the year instead of the time of day. 

-m, --format=commas List files horizontally, with as many as will fit on each line, separated by commas. 

-n, --numeric-uid-gid List thenumeric UID and GID instead of the names. 

-p Append a character to each filename indicating the file type 

-q, --hide-control-chars Print question marks instead of nongraphic characters in filenames. 

-r, --reverse Sort directory contents in reverse order. 

-s, --size Print the size of each filein 1K B blocks to the left of the filaaame If the environment 
variable PosIxLy_correct is set, 512-byte blocks are used instead. 

-t, --sort=time Sort directory contents by timestamp instead of alphabetically, with the newest files listed 
first. 

-u, --time=atime, Sort directory contents according to the files’ last access time instead of the modification 

--time=access, --time=use time. If the long listing format is being used, print the last access time instead of the 
modification time 
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-X,- 


-format=across, 


--format=horizontal 


-A, --almost-all 

-B, --ignore-backups 
-C, --format=vertical 
-F, --classify 

-G, --no-group 

-L, --dereference 

-N, --literal 

-Q, --quote-name 

-R, --recursive 

-S, --sort=size 

-U, --sort=none 

-X, --sort=extension 
-1, --format=single-column 
-w, --width cols 

-T, --tabsize cols 
-I, --ignore pattern 
--help 

--version 


List the files in columns, sorted horizontally. 


, 


List all files in directories, except for’.’ and‘..’. 
Do not list files that end with ~, unless they are given on the command line. 
List files in columns, sorted vertically. 


Append a character to each filename indicating the file type For regular files that are 
executable, append a «. T hefile type indicators are / for directories, efor symbolic links, | 
for FIFOs, = for sockets, and nothing for regular files. 


Inhibit display of group information in along format directory listing. 

List the files linked to by symbolic links instead of listing the contents of the links. 

Do not quote filenames. 

Enclose filenames in double quotes and quote nongraphic characters asin C. 

List the contents of all directories recursively. 

Sort directory contents by file size instead of alphabetically, with the largest files listed first. 
Do not sort directory contents; list than in whatever order they are stored on the disk. This 
option is not called -¢ because the UNIX 1s -f option also enables -a and disables -1, -s, 
and -+. It seems useless and ugly to group those unrelated things together in one option. 
Because this option doesn’t do that, it has a different name. 

Sort directory contents alphabetically by file extension (characters after the last period); files 
with no extension are sorted first. 

List one file pe line 

Assume the screm is cols columns wide. T he default is taken from the terminal driver if 
possible, otherwise, the environment variable coLumns is used if it is set; otherwise the 
default is so. 

Assume that each tab stop is cols columns wide The default iss. 

Do not list files whose names match the shdl pattern pattern unless they are given on the 
command line. Asin the shell, an initial period (.) in a filename does not match a wildcard 
at the start of pattern. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 








On BSD systems, the -s option reports sizes that are half the correct values for files that are N FS-mounted from H P-U X 
systems. On HP-UX systems, it reports sizes that are twice the correct values for files that are N FS-mounted from BSD 
systems. This is due to a flaw in H P-UX; it also affectsthe H P-UX 1s program. 


lsattr 


lsattr— List file attributes on a Linux second extended filesysten 


SYNOPSIS 


lsattr [ -Radv ] [ files... ] 


DESCRIPTION 


isattr lists the files attributes on an second extended filesystem. 


GNU FileUtilitie 


Ismod 


OPTIONS 

-R Recursivay list attributes of directories and their contents. 

-a List all files in directories, including files that start with period (.). 

-d List directories like other files, rather than listing thar contents. 

“V List the files version. 
AUTHOR 

lsattr hasbem written by Remy Card (cardemasi.ibp.fr), the devdoper and maintainer of the ext2 fs. 
BUGS 

There are none:-). 
AVAILABILITY 

lsattr is available for anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu iN /pub/linux/packages/ext2ts. 
SEE ALSO 

chattr(1) 

Vergon 0.5b, N ovenber 1994 

Ismod 

1smod— show the loaded modules 
SYNOPSIS 

1smod 
DESCRIPTION 


1smod shows information about all loaded modules. T he format is 


name size [list of referring modules ] 
size isin 4Kb pages. 
This information is a copy of the contents of /proc/modules. 


SEE ALSO 


insmod(1), modprobe(1), depmod(1), rmmod(1), ksyms(1), modules(2) 


HISTORY 


The module support was first conceived by Anonymous (as far as! Know... ). Linux version by Bas Laarhoven 
(bas@vimec.n1), 0.99.14 version by ] on Tombs (jonegtex@2.us.es), extended by Bjorn Ekwall (bjorn@biox.se). 


BUGS 
1smod might have some, but they are wel hidden... 
Linux, 14 May 1995 
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lynx 


lynx— A general-purpose distributed information browser for the W orld W ide W eb 


SYNOPSIS 


lynx [options] [path or URL] 


Use lynx -help to display acomplete list of current options. 


DESCRIPTION 


lynx is a fully-featured W orld Wide W eb (W WW) client for users running cursor-addressable, character-cell display devices 
(for example, vt100 terminals, vt100 emulators running on PCsor M acs, or any other “curses-oriented” display). It will 
display H ypertext M arkup Language (H T M L) documents containing links to files residing on the local system, as well as 
files residing on remote systems running Gopher, HTTP, FTP, WAIS, and NNTP servers. Current versions of lynx run on 


UNIX and VMS. 


lynx can be used to access information on the W orld Wide W @, or to build information systems intended primarily for 
local access. For example, 1ynx has been used to build several Campus W ide Information Systems (CW 1S). In addition, 1ynx 
can be used to build systems isolated within asingle LAN. 


OPTIONS 


At startup, lynx will load any local file or remote URL specified at the command line. For hdp with URLs, press ? or h while 
running lynx. Then follow the link titled “Hap on URLs.” 


-anonymous 
-ascii 
-auth=l D: PASSWD 
-book 


-buried_news 


-cache=NUMBER 
-case 
-Cfg=FILENAME 
-child 


-crawl 


-display=DI SPLAY 
-dump 


-editor=EDI TOR 
-emacskeys 


-enable_scrollback 


-error_file=Fl Le 
-euc 
-fileversions 


-force_html 


If the only argument is -, then 1ynx expects to receive the arguments from stdin. T his isto allow 
for the potentially very long command line that can be associated with the -get_data Or -post_data 
arguments. (See entries for each later in this list.) 

Used to specify the anonymous account. 

Disable kanji code translation when J apanese mode is on. 

Sé& authorization ID and password for protected documents at startup. 


Use the bookmark page as the startfile T he default or command line startfile is still set for the 
M ain screen command, and will be used if the bookmark page is unavailable or blank. 


T oggles scanning of news articles for buried references, and converts then to news links. N ot 
recommended because e-mail addresses enclosed in angle brackets will be converted to false news 
links, and uuencoded messages can be trashed. 

Se the nuwBer of documents cached in memory. The default is 10. 

Enable case-sensitive string searching. 

Specifies a lynx configuration file other than the default lynx. cfg. 

Exit on left-arrow in startfile, and disable save to disk. 

With -traversal, output each page to afile With -dump, format output as with -traversal, but to 
stdout. 

Se the display variable for X rexeced programs. 


Dumps the formatted output of the default document or one specified on the command line to 
standard out. This can be used in the following way: lynx -dump http: //ww.w3.org/default.html. 


Enable Edit mode using the specified ED1ToR (vi, ed, emacs, and So on). 

Enable Emacs-like key movement. 

Toggle compatibility with comm programs’ scrollback keys (may beincompatible with some 
packages). 

D efinea file where 1ynx will report H TTP access codes. 

Sé& kanji code to EU C when Japanese modeis on. 

Include all versions of filesin local VM S directory listings. 

Forces the first document to be interpreted as HTML. 


lynx 307 











-ftp Disable FT P access. 

-get_data Send form data from stdin using GET method and dump results. 

-head Send a HEAD request for the mime headers. 

-help Print this 1ynx command syntax usage message. 

-historical Toggles use of > or -> asaterminator for comments. 

-homepage=URL Set home page separate from start page. 

-image_links Toggles inclusion of links for all images. 

-index=URL Se the default index file to the specified URL. 

-jpn T oggles J apanese character translations on or off. 

-Link=UMBER Starting count for 1nk#.dat files produced by -crawl. 

-localhost Disable URLs that point to remote hosts. 

-locexec Enable local program execution from local files only (if 1ynx was compiled with local execution 
enabled). 

-mime_header Prints the mime header of a fetched document along with its source. 

-minimal Toggles minimal versus valid comment parsing. 

-nobrowse Disable directory browsing. 

-noexec Disable local program execution (default). 

-nolist Disable the link list feature in dumps. 

-nolog Disable mailing of error messages to document owners. 

-noprint Disable print functions. 

-noredir Prevents automatic redirection and prints a message with alink to thenew URL. 

-nostatus Disable the retrieval status messages. 

-number_links Force numbering of links. 

-post_data Send form data from stdin using post method and dump results. 

-print Enable print functions (default). 

-pseudo_inlines T oggles pseudo-atTs for inlines with no att string. 

-realm Restricts access to URLsin the starting realm. 

-reload Flushes the cache on a proxy server (only the first document affected). 

-restrictions=[option] Allows alist of services to be disabled selectively. The following list is printed if no options are 

[,option][,option]... specified. 





all— Restricts all options. 
bookmark --D isallow changing the location of the bookmark file. 
bookmark_exec --D isallow execution links via the bookmark file. 


Change_exec_perms— D isallow changing the execute permission on files (but still allow it for 
directories) when local file managenent is enabled. 


default --Same as command-line option -anonymous. D isables default services for anonymous users. 
Currently set to all restricted except for the following: inside telnet, outside telnet, inside_news, 
inside ftp, outside ftp, inside rlogin, outside rlogin, jump, mail, and goto. D efaults are settable 
within userdefs.h. 


dired_support— D isallow local file management. 

disk_save— D isallow saving binary files to disk in the download menu. 
download --D isallow downloaders in the download menu. 

editor— Disallow editing. 

exec --D isable execution scripts. 

exec_frozen--D isdlow the user from changing the local execution option. 
file_ur1--D isallow using goto to go to file URLs. 

goto— Disable the g (goto) command. 
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-rlogin 
-selective 


-show_cursor 


-Sjis 
-source 
-telnet 
-term=TERM 


-trace 


-traversal 


-underscore 
-validate 
-version 


-vikeys 


COMMANDS 


inside ftp— Disa 
selectivity.) 


low FTPs for people coming from inside your domain. (utmp required for 


inside_news— D isallow Usenet news posting for people coming from inside your domain. (utmp 


required for selecti 
inside_rlogin— D 
selectivity.) 
inside telnet--Di 
selectivity.) 
jump— Disable the j 





vity.) 
isallow rlogins for people coming from inside your domain. (utmp required for 


sallow T anetsfor people coming from inside your domain. (utmp required for 


(jump) Command. 


mail--D isable mailing feature. 
news_post--D isable U sanet news posting. 
options_save--D isallow saving optionsin .1ynxrc. 


outside ftp— Disal 
selectivity.) 


ow FTPs for people coming from outside your domain. (utmp required for 


outside_news— D isallow Usenet news posting for people coming from outside your domain. (utmp 


required for selectivi 
outside_rlogin— Di 
selectivity.) 
outside telnet— Di 
selectivity.) 





ty.) 
sallow rlogins for people coming from outside your domain. (utmp required for 


sallow T elnets for people coming from outside your domain. (utmp required for 


print— D isallow most print options. 
shell— D isallow shal escapes and 1ynxexec Or lynxprog goto’s. 
suspend --D isallow UNIX Ctrl+Z suspends with escape to shell. 


telnet_port— D isall 
Disable recognition 


ow specifying a port in T elnet goto’s. 
of rlogin commands. 


Require .www browsable files to browse directories. 


If enabled, the cursor will not be hidden in the right-hand corner but will instead be positioned at 
the start of the currently selected link. show_cursor is the default for systems without FANCy_CURSES 


capabilities, and the 
Sé& kanji code to Shi 
W orks the same as d 
Disable recognition 


Tell 1ynx what termi 
when, for example, 


default configuration can be changed in userdefs.h. 

ft JIS when J apanese mode is on. 

ump but outputs H TM L sourceinstead of formatted text. 
of T dnet commands. 


nal type to assume it’s talking to. (T his may be useful for renote execution 
ynx connects to arenote TCP/IP port that starts a script that, in turn, starts 


another lynx process.) 
Turnson WWW tracemode 


Traverse all H TTP links derived from startfile. When used with -craw1, each link that begins 
with the same string as startfile is output to afile, intended for indexing. See craWL. announce for 
more information. 


Toggles use of underline format in dumps. 

Accept only HTTP URLs (for validation). Complete security restrictions also areimplemented. 
Print version information. 

Enable vi-like key movement. 





m UseUp arrow and D own arrow to scroll through hypertett links. 
m@ Right arrow or Return will follow a highlighted hypertext link. 
m@ Left Arrow will retreat from a link. 


macptopbm 


@ Typen or? for onlinehdp and descriptions of keystroke commands. 
m Typek for acomplete list of the current keystroke command mappings. 


NOTES 
This is the Lynx 2.5 Release for UN *X/VMS. 


If you wish to contribute to the further: devdopment of 1ynx, subscribe to our mailing list. Send email to majordomo@sig.net 
with “subscribe lynx-dev” as the only line in the body of your message. 


Send bug reports, comments, and suggestions to 1ynx-devésig.net after subscribing. 


Unsubscribe by sending email to majordomo@sig.net with unsubscribe lynx-dev as theonly linein the body of your message. 
Do not send the unsubscribe message to the lynx -dev list itself. 


ACKNOWLEDGMENTS 


lynx has incorporated code from a variety of sources along the way. T he earliest versions of lynx included code from Earl 
Fogel of Computing Services at the University of Saskatchewan, who implemented Hyperrez in the UN *X environment. 
HYPERREZ Was developed by Nid Larson of Think.com and served asthe modal for the early versions of 1ynx. T hose versions 
also incorporated libraries from the UN *X Gopher clients devdoped at the U niversity of M innesota, and the later versions of 
lynx rely on the WW W client library code devdoped by Tim Berners-Lee and the WW W community. Also a special thanks 
to Foteos M acrides, who ported much of 1ynx to VMS and to everyoneon theN et who has contributed to 1ynx’s develop- 
ment either directly (through comments or bug reports) or indirectly (through inspiration and devdopment of other 
systems). 


AUTHORS 


Lou M ontulli, Garrett Blythe Craig Lavender, M ichael Grobe, Charles R ezac 
Academic Computing Services 

University of Kansas 

Lawrence, Kansas 66047 


Foteos M acrides 
W orcester Foundation 
Shrewsbury, M assachusetts 01545 
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macptopbm 

macptopbm— Convert aM acPaint file into a portable bitmap 
SYNOPSIS 

macptopbm [-extraskip N][macpfile] 
DESCRIPTION 

macptopbm reads a M acPaint file as input and produces a portable bitmap as output. 
OPTIONS 

-extraskip This flag is to get around a problem with some methods of transferring files from the M ac world to the 


UNIX world. M ost of these methods leave the M ac files alone, but a few of then add the find-erinfo data 
onto the front of the UN IX file. This means an extra 128 bytesto skip over when reading thefile. The 
symptom to watch for is that the resulting PBM file looks shifted to one side. If you get this, try - 
extraskip 128, and if that still doesn’t look right, try another value. 


All flags can be abbreviated to their shortest unique prefix. 
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SEE ALSO 


picttoppm(1), pbmtomacp(1), pom(5) 


AUTHOR 
Copyright © 1988 by J ef Poskanzer. The M acPaint-reading code is copyright © 1987 by Patrick]. Naughton 


(naughton@wind.sun.com), 


29 March 1989 


make 


make— GNU make utility to maintain groups of programs 


SYNOPSIS 


make [ -f makefile ] [ option ] ... target... 


WARNING 


This man page is an extract of the documentation of GN U make. It is updated only occasionally becausetheG N U project 
does not use nroff. For complete, current documentation, refer to the info filemake or theD VI filemake.dvi, which are 
made from the texinfo source file make. texinfo. 


DESCRIPTION 


The purpose of the make utility isto determine automatically which pieces of a large program need to be recompiled, and 
issue the commands to recompile them. T hismanual page describes the GN U implementation of make, which was written by 
Richard Stallman and Roland M cGrath. O ur examples show C programs because they are most common, but you can use 
make with any programming language whose compiler can berun with a shell command. In fact, make is not limited to 
programs. You can useit to describe any task where some files must be updated automatically from others whenever the 
others change. 


To prepare to use make, you must write a file called the makefile that describes the rdationships among files in your program 
and states the commands for updating each file In a program, typically, the executable file is updated from object files, 
which arein turn made by compiling source files. 


Oncea suitable makefile exists, each time you change some source files, this simple shal command: 


make 


suffices to perform all necessary recompilations. T he make program uses the makefile database and the last-modification times 
of the files to decide which of the files need to be updated. For each of thosefiles, it issues the commands recorded in the 
database. 


make executes commands in the makefile to update one or more target names, whee name is typically a program. If no -f 
option is present, make will look for the makefiles GnU-makefile, makefile, and Makefile, in that order. 


Normally you should call your makefile either makefile Or Makefile. (We recommend Makefile because it appears promi- 
nently near the beginning of a directory listing, right near other important files such as README.) T he first name checked, 
GNUmakefile, isnot recommended for most makefiles. You should use this name if you have a makefile that is specific to 
GNU make, and will not be understood by other versions of make. If makefile iS-, the standard input is read. 


make updates a target if it depends on prerequisite files that have been modified since the target was last modified, or if the 
target does not exist. 


make [= | 


OPTIONS 
-b, -m T hese options are ignored for compatibility with other versions of make. 
-C dir Change to directory dir before reading the makefiles or doing anything dse. If multiple -c options are specified, 


each is interpreted relative to the previous one: -c / -c etc is equivalent to -c /etc. Thisis typically used with 
recursive invocations of make. 

-d Print debugging information in addition to normal processing. The debugging information says which files are 
being considered for remaking, which file times are bang compared and with what results, which files actually 
need to be remade, which implicit rules are considered and which are applied— everything interesting about how 
make decides what to do. 


-e Give variables taken from the environment precedence over variables from makefiles. 

-f file Usefile asamakefile 

-i Ignore all errors in commands executed to remake files. 

-I dir Specifies a directory dir to search for included makefiles. If several -1 options are used to specify several directo- 


ries, the directories are searched in the order specified. U nlike the arguments to other flags of make, directories 
given with -1 flags may comedirectly after the flag: -1dir is allowed, as well as -1 dir. This syntax is allowed for 
compatibility with the C preprocessor’s -1 flag. 

-j jobs Specifies the number of jobs (commands) to run simultaneously. | f there is more than one -j option, thelast one 
is effective. If the-j option isgiven without an argument, make will not limit thenumber of jobs that can run 
simultaneously. 


-k Continue as much as possible after an error. Although the target that failed, and those that depend on it, cannot 
be remade, the other dependencies of these targets can be processed all the same 

-1, Specifies that no new jobs (commands) should be started if there are other jobs running and theload average is at 

-lload least | oad (afloating-point number). With no argument, removes a previous load limit. 

-n Print the commands that would be executed, but do not execute them. 


-o file Donotremakethefile file even if it is older than its dependencies, and do not renake anything because of 
changes in file. Essentially, the file is treated as very old and its rules are ignored. 





-p Print the database (rules and variable values) that results from reading the makefiles; then execute as usual or as 
otherwise specified. T his also prints the version information given by the -v switch (see below). To print the 
database without trying to remake any files, use make -p -f/dev/null. 

-q Question mode. Do not run any commands or print anything; just return an exit status that is zero if the specified 
targets are already up-to-date nonzero otherwise. 

-r Eliminate use of the built-in implicit rules. Also clear out the default list of suffixes for suffix rules. 

-s Silent operation; do not print the commands as they are executed. 

-S Cancel the effect of the -k option. This is never necessary except in a recursive make where -k might be inherited 
from the top-level make via MAKEFLAGs or if you set -k in MAKEFLAGS in your environment. 

-t Touch files (mark then up-to-date without really changing them) instead of running thar commands. T hisis 
used to pretend that the commands were done, in order to fool future invocations of make. 

-v Print the version of the make program plus a copyright, alist of authors, and anotice that there is no warranty. 


After this information is printed, processing continues normally. To get this information without doing anything 
else, use make -v -f/dev/null. 


-w Print a message containing the working directory before and after other processing. T his may be useful for 
tracking down errors from complicated nests of recursive make commands. 


-W file Pretend that the target file has just been modified. W hen used with the -n flag, this shows you what would 
happen if you were to modify that file. Without -n, it isalmost the same as running a touch command on the 
given file before running make, except that the modification time is changed only in the imagination of make. 


SEE ALSO 


/usr/local/doc/gnumake.dvi 


TheGNU MakeM anual 
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BUGS 
See the chapter “Problems and Bugs’ inTheGNU M akeM anual. 


AUTHOR 
This manual page contributed by D ennis M orse of Stanford U niversity. It has been reworked by Roland M cGrath. 
GNU, 22 August 1989 


makedepend 


makedepend— C reate dependencies in makefiles 


SYNOPSIS 
makedepend [ -Dname=def ][-Dname ][-Iincludedir ][-Yincludedir ][-a ] 
[-fmakefile ][-oobjsuffix ][-pobjprefix ][-sstring ][-wwidth ][-v ][-m ] 
[--otheroptions -- ] sourcefile ... 


DESCRIPTION 


makedepend reads each sourcefile in sequence and parses it like a C-preprocessor, processing all #include, #define, #undef, 
#ifdef, #ifndef, #endif, #if and #else directives so that it can correctly tal which #include, directives would be used in a 
compilation. Any #include, directives can reference files having other #include directives, and parsing will occur in these files 
as well. 


Every file that a source file includes, directly or indirectly, is what makedepend calls a dependency. T hese dependencies are then 
written to amakefilein such a way that make(1) will know which object files must be recompiled when a dependency has 
changed. 

By default, makedepend places its output in the file named makefile if it exists; otherwise, Makefile. An alternate makefile may 
be specified with the -+ option. It first searches the makefile for the line 

# DO NOT DELETE THIS LINE -- make depend depends on it. 

or one provided with the -s option, asa ddimiter for the dependency output. If it findsit, it will delete everything following 
this to the end of the makefile and put the output after this line If it doesn’t find it, the program will append the string to 


the end of the makefile and place the output following that. For each sourcefile appearing on the command line, makedepend 
puts lines in the makefile of the form: 


sourcefile.o: dfile... 


whee sourcefile.o isthename from the command line with its suffix reolaced with .o, and dfile isa dependency 
discovered in a #include directive while parsing sourcefile or oneof thefilesit included. 


EXAM PLE 


Normally, makedepend will be used in a makefile target so that typing makedepend will bring the dependencies up-to-date for 
the makefile. For example, 


SRCS = filel.c file2.c... 
CFLAGS = -0 -DHACK -I../foobar -xyz 


depend: 
makedepend -- $(CFLAGS) -- $(SRCS) 
OPTIONS 
makedepend will ignore any option that it does not understand so that you may use the same arguments that you would for 
cc(1). 


-Dname=def or Define. This places a definition for name in makedepend’s symbol table. Without =def, the symbol becomes 
-Dname defined as 1. 


makedeoend [= | 


-Iincludedir Include directory. This option tdls makedepend to prepend includedir to its list of directories to search 
when it encounters a #include directive. By default, makedepend only searches the standard include 
directories (usually /usr/include and possibly a compiler-dependent directory). 

-Yincludedir Replace all of the standard include directories with the single specified include directory; you can omit the 
includedir to simply prevent searching the standard include directories. 


-a Append the dependencies to the end of the file instead of replacing then. 
-fmakefile Filename. T his allows you to specify an alternate makefile in which makedepend can place its output. 
-oobj suffix O bject file suffix. Some systems may have object files whose suffix is something other than .o. This option 


allows you to specify another suffix, such as .b with -o.b or :obj with -o:obj and so forth. 


-pobjprefix O bject file prefix. T he prefix is preoended to the name of the object file. T his is usually used to designate a 
different directory for the object file. The default is the enpty string. 





-sstring Starting string delimiter. This option permits you to specify a different string for makedepend to look for in 
the makefile. 

-wwidth Line width. Normally, makedepend will ensure that every output line that it writes will be no wider than 78 
characters for the sake of readability. This option enables you to change this width. 

-v Verbose operation. This option causes makedepend to emit the list of files included by each input file on 
standard output. 

-m Warn about multiple inclusion. T his option causes makedepend to producea warning if any input file 


includes another file more than once. In previous versions of makedepena, this was the default behavior; the 
default has been changed to better match the behavior of theC compiler, which does not consider 
multiple inclusion to be an error. T his option is provided for backwards compatibility, and to aid in 
debugging problems related to multipleinclusion. 

-- options -- __ If makedepend encounters a double hyphen (--) in the argument list, then any unrecognized argument 
following it will be silently ignored; a second double hyphen terminates this special treatment. In this way, 
makedepend can be madeto safely ignore esoteric compile’ arguments that might normally be found in a 
CFLAGS make macro. (See the preceding “Example” section.) All options that makedepend recognizes and that 
appear between the pair of double hyphens are processed normally. 


ALGORITHM 


The approach used in this program enables it to run an order of magnitude faster than any other dependency generator | 
have ever seen. Central to this peformance are two assumptions: that all files compiled by asingle makefile will be compiled 
with roughly the same -1 and -p options; and that most filesin a single directory will include largdy the same files. 


Given these assumptions, makedepend expects to be called once for each makefile, with all source files that are maintained by 
the makefile appearing on the command line It parses each source and include file exactly once maintaining an internal 
symbol table for each. T hus, the first file on the command line will take an amount of time proportional to the amount of 
time that anormal C preprocessor takes. But on subsequent files, if it encounters an include file that it has already parsed, it 
does not parse it again. 





For example, imagine you are compiling two files, file1.c and file2.c; they both includethe header file header.h, and the 
file header.h in turn includes the files def1.h and def2.h. When you run the command: 


makedepend file1.c file2.c 


makedepend will parse file1.c and consequently, header.h and then deft.h and def2.h. It then decides that the deoendencies 
for this file are 


filet.o: header.h defi.h def2.h 


But when the program parses file2.c and discovers that it, too, includes header.h, it does not parse thefile, but simply adds 
header.h, def1.h, and def2.h to the list of dependencies for file2.o. 


SEE ALSO 
cc(1), make(1) 
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BUGS 
makedepend parses, but does not currently evaluate, the SVR4 #predicate(token-list) preprocessor expression; such 
expressions are simply assumed to be true. This may cause the wrong #include directives to be evaluated. 


Imagine you are parsing two files, say file1.c and file2.c, and each includes the file def.h. The list of files that def .h 
includes might truly be different when def.h is included by filet.c than when it is included by file2.c. But when 
makedepend arrives at a list of deoendencies for a file it is cast in concrete. 


AUTHOR 
Todd Brunhoff, T ektronix, Inc. and MIT Project Athena 
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makestrs 


makestrs— M ake string tableC source and header(s) 


SYNOPSIS 


makestrs [-f source] [-abioptions ...] 


DESCRIPTION 


Themakestrs command creates string table C source files and headers. If -# source isnot specified, makestrs will read from 
stdin. TheC source file is always written to stdout. makestrs Creates one or more C header files as specified in the source file 
The following options may be specified: -sparcabi, -intelabi, -functionabi, -arrayperabi, aNd -defaultabi. 


-sparcabi isused on SPARC platforms conforming to the SPARC Compliance D efinition, i.e, SVR4/Solaris. 
-intelabi used on Intel platforms conforming to the Systen V Application Binary Interface (SVR 4). 


-earlyR6éabi May be used in addition to -intelabi for tuations where the vendor wishes to maintain binary compatibility 
between X11R6 public-patch 11 (and earlier) and X11R6 public-patch 12 (and later). 


-functionabi generates a functional application binary interface to the string table T his mechanism imposes a severe 
performance penalty and it’s recommended that you not use it. 


-arrayperabi results in a separate array for each string. T his is the default behavior if makestrs was compiled with - 
DARRAYPERSTR (it almost never is). 


-defaultabi forces the generation of the “normal” string table even if makestrs was compiled with -DARRAYPERSTR. makestrs IS 
almost never compiled with -parrayperstr, SO this is the default behavior if no application binary interface (ABI) options are 
specified. 


SYNTAX 
T he syntax for string-list file is as follows (items in square brackets are optional): 


#prefix <text> 
#feature <text> 
externref <text> 
externdef [<text>] 
#ctempl <text>] 
ile <filename> 
able <tablename> 
#htempl] <text> 


_ oF tO te 


<text> 
#table <tablename> 
<text> 
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<text> 


#table <tablename> 
Pe <filename> 
+] 
You may have one or more #file directives. Each #file may have one or more #table directives. 
The #prefix directive determines the string that makestr will prefix to each definition. 
The #feature directive determines the string that makestr will use for the feature-test macro, for example, x"STRINGDEFINES. 


The #externref directive determines the string that makestr will use for the extern clause; typically this will be extern, but 
M otif wants it to be externalref. 


The #externdef directive determines the string that makestr will use for the declaration; typically, this will be the null string, 
and M otif will use externaldet (_xmstrings). 


The #ctmp1 directive determines the name of the file used asa tenplate for the C source file that is generated. 


Each #file <filename> directive will result in a corresponding header file by that name containing the appropriate definitions 
as specified by command-line options. A single C source file containing the declarations for the definitions in all the headers 
will be printed to stdout. 


The #htmp1 directive determines the name of the file used as a template for the C header file that is generated. 


Each #table <tabl ename> directive will be processed in accordance with the ABI. On most platforms, all tables will be 
catenated into a single table with the name of the first table for that file To conform to the|Intd ABI, separate tables will be 
generated with the names indicated. 


The template files specified by the #ctmp1 and #htmp1 directives are processed by copying line for line from the template file 
to the appropriate output file T he line containing the string <<<STRING_TABLE_GOES_HERE>>> iSnot copied to the output file. 
The appropriate data is then copied to the output file and then the renainder of the template file is copied to the output file. 


BUGS 


makestrs iS not very forgiving of syntax errors. Sometimes you need a trailing space after # directives, other times they will 
mess you up. N o warning messages are emitted. 


SEE ALSO 
SPARC Compliance D efinition 2.2, SPARC International Inc., 535 M iddlefield Road, Suite 210, M enlo Park, CA 94025 


System V Application Binary Interface Third Edition, ISBN 0-13-100439-5, UNIX Press, PTR Prentice H all, 113 Sylvan 
Avenue, Englewood Cliffs, NJ 07632 


System V Application Binary Interface Third Edition, Intd386 Architecture Processor Supplement, ISBN 0-13-104670-5, 
UNIX Press, PTR Prentice H all, 113 Sylvan Avenue, Englewood Cliffs, NJ 07632 


System V Application Binary Interface Third Edition, SPARC Architecture Processor Supplement, ISBN 0-13-104696-9, 
UNIX Press, PTR Prentice H all, 113 Sylvan Avenue, Englewood Cliffs, NJ 07632 
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mattrib 


mattrib— Change M S-D OS file attribute flags 
SYNOPSIS 


mattrib [ -a;ta ][-h{t+h ][-rj+r ][-s|+s ] msdosfile [ msdosfiles... ] 


Part |: User Commands 


DESCRIPTION 
mattrib adds attribute flags to an MS-DOS file (with the+ operator) or renoves attribute flags (with the - operator). 
mattrib allows the following command-line options: 


a Archive bit. Used by some backup programs to indicate a new file. 
r Read-only bit. U sed to indicate a read-only file. Files with this bit set cannot be erased by pet or modified. 
s System bit. U sed by M S-D OS to indicatean operating system file. 
h Hidden bit. Used to make files hidden from ptr. 
SEE ALSO 
mtools(1) 


Local 


mbadblocks 


mbadblocks— Scan an M S-D OS floppy and mark its unused bad blocks as bad. 
SYNOPSIS 


mbadblocks drive: 


DESCRIPTION 
mbadblocks scans an M S-D OS floppy for bad blocks. All unused bad blocks are marked as such in the FAT. Thisis intended 
to be used right after mformat. It is not intended to salvage bad disks. 

SEE ALSO 


mtools(1) 


BUGS 


This should (but doesn’t :-( ) also try to salvage bad blocks that are in use by reading them repeatedly, and then mark then 
bad. 


mcd 


med— Change M S-DOS directory 
SYNOPSIS 


mcd [ msdosdirectory ] 


DESCRIPTION 


Without arguments, mca will report the current device and working directory. O therwise, mca changes the current device and 
current working directory relative to an MS-DOS filesystem. 


The environmental variable mcwo may be used to locate the file where the device and current working directory information is 
stored. T he default is $Home/ .mcwd. Information in this fileis ignored if the file ismore than six hours old. 


MS-DOS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the directory name to be enclosed in quotes to protect it from the shell. 


med returns @ on success or 1 on failure. 


SEE ALSO 
mdir(1) 


mcopy 317 


BUGS 
Unlike MS-DOS versions of CD, mca can be used to change to another device. 
It may be wise to remove old .mewa files at logout. 
Local 


mcookie 


mcookie— Generate magic cookies for xauth 


SYNOPSIS 


mcookie 


DESCRIPTION 
meookie generates a 128-bit random hexadecimal number for use with the X authority system. T ypical usage: 


xauth add :®@ . ‘mcookie' 
SEE ALSO 
x(1), xauth(1) 
12 February 1995 
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mcopy— Copy MS-DOS files to/from UN 1X 


SYNOPSIS 
mcopy [ -tnvmoOsSrRA ] sourcefile targetfile 
mcopy [ -tnvmoOsSrRA ] sourcefile [ sourcefiles... ] targetdirectory 
mcopy [ -tnvm ] MSDOSsourcefile 

DESCRIPTION 


mcopy Copies the specified file to the named file, or copies multiple files to the named directory. The source and target can be 
either MS-DOS or UN IX files. 


The use of a drive letter designation on the M S-D OS files— a: for example— determines the direction of the transfer. A 
missing drive designation implies a U NIX file whose path starts in the current directory. If a source drive letter is specified 
with no attached filename (for example, mcopy a: .), all files are copied from that drive. 


If only asingle, MS-D OS source parameter is provided (for example, mcopy a:foo.exe), an implied destination of the current 
directory (.) is assumed. 


A filename of - means standard input or standard output, depending on its position on the command line. 
meopy Will allow the following command-line options: 


t Text file transfer. mcopy will translate incoming carriage return/line feeds to line feeds. 
n No warning. mcopy will not warn the user when overwriting an existing file 

v Verbose mode. 

m Preserve the file modification time 


If the target file already exists, and the -n option isnot in effect, mcopy asks whether to overwrite the file or to rename the new 
file. (See the mtools(1) man page for details.) 


Part |: User Commands 


SEE ALSO 


mtools(1), mread(1), mwrite(1) 


BUGS 
Unlike MS-DOS, the + operator (append) from M S-D OS is not supported. 
Local 


md5sum 


md5sum— G enerate/check M D 5 message digests 
SYNOPSIS 


md5sum [-bv][-c [ file ]] 
md5sum file ... 


DESCRIPTION 


md5sum generates and checks M D 5 message digests, as described in RFC-1321. T hemessage digest produced can be thought 
of as a 128-bit “signature” of the input file Typically, ma5sum is used to verify the integrity of files made available for 
distribution via anonymous FT P (for example, announcements for new versions of irc(1) usually contain M D5 signatures). 
M essage digests for a tree of files can be generated with a command similar to the following: 


find . -type f -print | xargs md5sum 


The output of this command is suitable as input for the -c option. 


OPTIONS 
-c [file] Check message digests. Input is taken from stdin or from the specified file. The input should bein the 
same format as the output generated by massum. 
-v Verbose. Print filarames when checking. 
-b Read filesin binary mode otherwise, end-of-file conventions will be ignored. 
HISTORY 


The md5sum program was written by Branko Lankester and may be freely distributed. T he original source code is in the M IT 
PGP 2.6.2 distribution. Those concerned about the integrity of this version should obtain the original sources and compile 
their own version. 


Theunderlying implementation of Ron Rivest’s MD 5 algorithm was written by Colin Plumb and isin the public domain. 
(Equivalent code is also availablefrom RSA D ata Security, Inc.) 


SEE ALSO 
sum(1), cksum(1), pgp(1) 
Linux 1.0, 11 February 1995 


mdel 


mdel— D dete an MS-DOS file 
SYNOPSIS 


mdel [ -v ] msdosfile [ msdosfiles... ] 


mdir 


DESCRIPTION 
mde1 deletes a file on an MS-DOS filesystem. 


mde will allow the following command-line option: 
v Verbose mode. Echo the filenames as they are processed. 


mde1 will ask for verification prior to renoving a read-only file. 
SEE ALSO 


mtools(1) 
Local 


mdeltree 


mdeltree— Removean MS-DOS directory tree 


SYNOPSIS 


mdeltree [ -v ] msdosdirectory [ msdosdirectories... ] 


DESCRIPTION 


mdeltree removes a directory and all thefiles and subdirectories it contains from an MS-DOS filesystem. mdeltree will allow 
the following command-line option: 


v Verbose mode. Displays each file or directory as it isrenoved. 
An error occurs if the directory does not exist. 


SEE ALSO 


mtools(1), mrd(1) 


Local 

mdir 

mdir— Display an MS-DOS directory 
SYNOPSIS 

mdir [ -w ] msdosdirectory 

mdir [ -w ][-a ] msdosfile [ msdosfiles... ] 
DESCRIPTION 

mdir displays the contents of an MS-DOS directory. 

mdir will allow the following command-line options: 

w W ide output. T his option will print the filevames across the page without displaying the file size or creation date. 


a Also list hidden files. 
An error occurs if a component of the path is not adirectory. 
SEE ALSO 


mtools(1) 
Local 
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merge 
merge— T hree-way file merge 
SYNOPSIS 
merge [ options ] filel file2 file3 
DESCRIPTION 


merge incorporates all changes that lead fromfile2 tofile3 intofile1. Theresult ordinarily goes into file1. merge is useful 
for combining separate changes to an original. Supposefile2 isthe original, and both fiie1 andfile3 are modifications of 
file2. Then merge combines both changes. 

A conflict occurs if both fi!e1 andfile3 have changes in acommon segment of lines. If a conflict is found, merge normally 
outputs a warning and brackets the conflict with <<<<<<< and >>>>>>> lines. A typical conflict will look like this: 


<<<<<<< file A 
lines in file A 


lines in file B 
>>>>>>> file B 


If there are conflicts, the user should edit the result and delete one of the alternatives. 


OPTIONS 
-A Output conflicts using the -a style of ditr3(1), if supported by ditt3. This merges all changes leading from file2 
to file3 into file1, and generates the most verbose output. 


-E, -e T hese options specify conflict styles that generate less information than -a. See aiff3(1) for details. The default is 
-E. With -e, merge does not warn about conflicts. 


-L label Thisoption may begiven up to three times, and specifies labels to be used in place of the corresponding filenames 
in conflict reports. That is, merge-Lx-L y -Lz a b c generates output that looks like it came from files x, y, and z 
instead of from files a, b, and c. 


-p Send results to standard output instead of overwriting filet. 
-q Quiet; do not warn about conflicts. 
-V Print RCS’s version number. 


DIAGNOSTICS 


Exit status is for no conflicts, 1 for some conflicts, 2 for trouble. 


IDENTIFICATION 
Author: Walter F. Tichy. 
M anual Page Revision: 5.7; Release D ate: 1995/06/01. 
Copyright © 1982, 1988, 1989 Walter F. Tichy. 
Copyright © 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 
SEE ALSO 


ditf3(1), dift(1), resmerge(1), co(1) 


BUGS 
It normally does not make sense to merge binary files as if they were text, but merge tries to do it anyway. 
GNU, 1June1995 
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mesg 


mesg— Display (do not display) messages from other users 


SYNOPSIS 


mesg [n] ly] 


DESCRIPTION 


The mesg utility is invoked by a users to control write access others have to the taminal device associated with the standard 
error output. If write access is allowed, then programs such as ta1k(1) and write(1) may display messages on the terminal. 


Traditionally, write access is allowed by default. H owever, as users become more conscious of various security risks, there isa 
trend to remove write access by default, at least for the primary login shall. To make sure your ttys are set the way you want 
them to be set, mesg should be executed in your login scripts. 


O ptions available: 

n D isallows messages 

y Permits messages to be displayed 

If no arguments are given, mesg displays the present message status to the standard error output. 
The mesg utility exits with one of the following values: 


\o M essages are allowed. 

\ M essages are not allowed. 

1 An error has occurred. 
FILES 

/dev/[pt]ty[ pq]? 
SEE ALSO 

bift(1), talk(1), write(1), wal1(1), login(1), xterm(1) 
HISTORY 


A mesg command appeared in version 6AT&T UNIX. 
Linux 1.2, 10 M arch 1995 
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mformat— Add an MS-D OS filesystem to a low-level formatted disk 


SYNOPSIS 
mformat [ -t tracks ] [ -h heads ] [ -s sectors ] [ -1 volume label ] 
[ -S sizecode ] [ -2 sectors on track @ ] [ -M software sector size ] 
[ -a ][-X ][-C ][-H hidden sectors ] drive: 

DESCRIPTION 


mformat adds a minimal M S-D OS filesystem (boot sector, FAT, and root directory) to a disk that has already been formatted 
by aUNIX low-levd format. 

The follow options are supported: (Thes, 2, 1, and m options may not exist if this copy of mtools has been compiled without 
the usE_2m option). 
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t The number of tracks (not cylinders). 
h Thenumber of heads (sides). 
s Thenumber of sectors per track. If the 2m option is given, number of 512-byte sector equivalents on generic tracks 


(that is, not head @ track). |f the 2m option is not given, number of physical sectors per track (which may be bigger 
than 512 bytes). 


1 An optional volume label. 

s The sizecode The size of thesector is2 * (sizecode + 7). 

2 2m format. The parameter to this option describes the number of sectors on track 0, head @. This option is 
recommended for sectors bigger than normal. 

1 Don’t use a 2m format, even if the current geometry of the disk is a 2m geometry. 

M Software sector size. T his parameter describes the sector size in bytes used by the M S-D OS filesystem. By default 
it isthe physical sector size. 

a If this option is given, an Atari-style serial number is generated. Ataris store their serial number in theO EM label. 

X Formats the disk as an Xdf disk. Xdf disks are used by O S/2. This format can hold 1756Kb, and is faster than the 
equivalent 2m formats. T he disk has first to be low-level formatted using the xdfcopy utility included in the fdutils 
package. 

C Creates the disk image file to install the M S-D OS filesystem on it. O bviously, this is useless on physical devices 
such as floppies and hard disk partitions. 

H Number of hidden sectors. T his parameter is useful for formatting hard disk partitions, which are not aligned on 


track boundaries (in other words, first head of first track doesn’t belong to the partition, but containsa partition 
table). In that case the number of hidden sectors is in general the number of sectors per cylinder. This is untested. 


n Serial number. 


To format adisk at adensity other than the default, you must supply (at least) those command-line parameters that are 
different from the default. 


Mformat returns @ on success or 1 on failure. 


SEE ALSO 


mlabel(1) 


BUGS 
Requires a low-level format utility from UNIX. 
D oesn’t detect (or record) bad block information. 
Local 


mgrtopom 


mgrtopbm— Convert an M GR bitmap into a portable bitmap 
SYNOPSIS 


mgrtopbm [mgrfile] 


DESCRIPTION 


mgrtopbm reads an MGR bitmap asinput and produces a portable bitmap as output. 


SEE ALSO 


pbmtomgr(1), pom(5) 
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24 January 1989 


AUTHOR 
Copyright © 1989 by J ef Poskanzer. 


mkdir 


mkdir— M ake directories 


SYNOPSIS 


mkdir [-p] [-m mode] [--parents] [--mode=mode] [--help] [--version] dir... 


DESCRIPTION 


This manual page documents the GN U version of mkdir. mkdir creates a directory with each given name. By default, the 
mode of created directories is 0777 minus the bits set in the umask. 


OPTIONS 


-m, --mode mode Se themode of created directories to mode, which is symbolic asin chmod and uses the default mode as the 
point of departure 

-p, --parents | Ensure that each given directory exists. Create any missing parent directories for each argument. Parent 
directories default to the umask modified by u+wx. Do not consider an argument directory that already 
exists to be an error. 


--help Print a usage message on standard output and exit successfully. 
--version Print version information on standard output then exit successfully. 
GNU FileU tilities 

mkdirhier 

mkdirhier— M ake a directory hierarchy 
SYNOPSIS 

mkdirhier directory ... 
DESCRIPTION 


The mkdirhier command creates the specified directories. Unlike mkdir, if any of the parent directories of the specified 
directory do not exist, it creates then as well. 


SEE ALSO 
mkdir(1) 
X Version 11 Release 6 


mkfifo 


mkfifo— M ake FIFOs (named pipes) 
SYNOPSIS 


mkfifo [-m mode] [--mode=mode] [--help] [--version] filename... 


Part |: User Commands 


DESCRIPTION 
This manual page documents the GN U version of mkfifo. mkfifo creates a FIFO with each given name. By default, the mode 
of created FIFOs is 0666 minus the bits set in the umask. 

OPTIONS 


-m, --mode mode Se themode of created FIFOs to mode, which issymbolic asin chmod and uses the default mode as the 
point of departure 


--help Print a usage message on standard output and exit successfully. 
--version Print version information on standard output then exit successfully. 
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mkmanifest— Create a shall script to restore UNIX filenames 


SYNOPSIS 


mkmanifest [ files ] 


DESCRIPTION 


mkmanifest Creates a shell script that will aid in the restoration of UNIX filenames that got clobbered by theM S-D OS 
filename restrictions. MS-DOS filenames are restricted to aght-character names, three-character extensions, uppercase only, 
no devicenames, and no illegal characters. 





Themkmanifest program is compatible with the methods used in pcomn, arc, and mtools to change pefectly good UNIX 
filenames to fit the M S-D OS restrictions. 


EXAMPLE 
Say you want to copy the following UNIX files to an MS-DOS disk (using themcopy command): 


very_long_name 
2.many.dots 
illegal: 
good.c 

prn.dev 
Capital 


mcopy will convert the names to 


very_lon 
2xmany.dot 
illegalx 
good.c 
xprn.dev 
capital 


The command: 


mkmanifest very_long_name 2.many.dots illegal: good.c prn.dev Capital > manifest 


would produce the following: 


mv very_lon very_long_name 
mv 2xmany.dot 2.many.dots 
mv illegalx illegal: 

mv xprn.dev prn.dev 

mv capital Capital 


<= 
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Suppose | 've copied these files from the disk to another UNIX system, and! now want thefiles back to thar original names. 
If the file manifest (the output captured above) was sent along with those files, it could be used to convert the filenames. 


BUGS 


The short names generated by mkmanifest follow the old convention (from mtoo1s-2.0.7) and not the one from Windows 95 
and mtools-3.0. 


SEE ALSO 


arc(1), pcomm(1), mtoo1s(1) 


N otice that good.c did not require any conversion, so it did not appear in the output. 


Local 


mknod 


mknod— M ake special files 


SYNOPSIS 


mknod [options] filename {bcu} major minor 
mknod [options] filename p 


O ptions: 


[-m mode] [--mode=mode] [--help] [--version] 


DESCRIPTION 


This manual page documents the GN U version of mknod. mknod creates a FIFO, character special file, or block special file with 
the given filerame By default, themode of created files is0666 minus the bits set in the umask. 


The argument after filename specifies the type of file to make: 


p for aFIFO 
b for ablock (buffered) special file 
c or u for a character (unbuffered) special file 


W hen making a block or character special file, the major and minor device numbers must be given after the file type. 


OPTIONS 
-m, --mode mode Set themode of created files to mode, which is symbolic as in chmod and uses the default mode as the point 
of departure. 
--help Print a usage message on standard output and exit successfully. 
--version Print version information on standard output then exit successfully. 
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mlabel 


mlabel— M akean MS-DOS volumelabel 


SYNOPSIS 


mlabel [ -v ] drive: [ newlabel ] 


Part |: User Commands 


DESCRIPTION 


mlabel displays the current volume label, if present. If new_| abel isnot given, and if nather the c nor thes options are set, it 
prompts the user for anew volume label. To ddete an existing volume label, press return at the prompt. 


mlabe1 supports the following command-line option: 


v Verbose mode. Display the new volume label if the label supplied is invalid. 
c Clears an existing label, without prompting the user. 
s Shows the existing label, without prompting the user. 


Reasonable care is taken to create a valid MS-DOS volume labd. If an invalid label is specified, miabe1 will change the label 
(and display the new labe if the verbose mode is set). 


Mlabe1 returns @ on success or 1 on failure. 


SEE ALSO 

mformat(1) 

Local 

mmd 

mmd— M ake an M S-D OS subdirectory 
SYNOPSIS 

mmd [ -voOsSrRA ] msdosdirectory [ msdosdirectories... ] 
DESCRIPTION 

mmd makes a new directory on an MS-DOS filesystem. 

md will allow the following command-line option: 

v Verbose mode. Display the new directory name asit is created. 

An error occurs if the directory already exists. 
SEE ALSO 

mtools(1), mrd(1), 

Local 

mmount 

mmount— M ount an M S-D OS disk 
SYNOPSIS 

mmount msdosdrive [mountargs] 
DESCRIPTION 


mmount reads the boot sector of an M S-D OS disk, configures the drive geometry, and finally mounts it, passing mountargs to 
mount. If no mount arguments are specified, the name of the device is used. If the disk is write protected, it is automatically 
mounted read-only. 


SEE ALSO 
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mtools(1), mount(8) 


mmove 


Local 


mmove— M oveor rename an existing M S-D OS file or subdirectory 


SYNOPSIS 

mmove [ -voOsSrRA ] sourcefile targetfile 

mmove [ -voOsSrRA ] sourcefile [ sourcefiles... ] targetdirectory 
DESCRIPTION 


mmove Moves or renames an existing M S-D OS file or subdirectory. 


mmove will allow the following command-line option: 


Vv 


Verbose mode. D isplay the new filename if the name supplied isinvalid. 


Additionally, it allows the clash-handling options described in the man page for mtools. 


MS-DOS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the names to be enclosed in quotes to protect them from the shal. Unlike the MS-DOS version of move, mmove is able 
to move subdirectories. 


SEE ALSO 


mren(1), mtoo1s(1) 


more 


more— File perusal filter for crt viewing 


SYNOPSIS 


more [-dlfpcsu] [-num] [+/ pattern] [+ linenum] 


DESCRIPTION 


more iS a filter for paging through text one screenful at a time. This version is especially primitive. U sers should realize that 
less(1) provides more(1) enulation and extensive enhancements. 


OPTIONS 


Command-line options are described in the following list. O ptions are also taken from the environment variable more (make 
sure to precede then with ahyphen (-)) but command-line options will override them. 


-num 
-d 


This option specifies an integer that is the screm size (in lines). 
more Will prompt the user with the message [Press space to continue, ‘q' to quit.] and will display [Press ‘h' 
for instructions. ] instead of ringing the bell when an illegal key is pressed. 


more usually treats (form feed) asa special character, and will pause after any line that contains a form feed. The -1 
option will prevent this behavior. 


Causes more to count logical, rather than scree lines (that is, long lines are not folded). 
Do not scroll. Instead, clear the whole screm and then display the text. 
Do not scroll. Instead, paint each screen from the top, clearing the renainder of each line asit is displayed. 
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Zs) 
-u 
+/ 


+num 


COMMANDS 


Squeeze multiple blank lines into one. 

Suppress underlining. 

The+/ option specifies a string that will be searched for before each file is displayed. 
Start at line number. 


Interactive commands for more are based on vi(1). Some commands may be preceded by a decimal number, called k in the 
following descriptions. In the following descriptions, *x means control-x. 


h OF ? 


SPAC| 


Z 


RETURN 
dor *D 
q OF Q INTERRUPT 


Ss 


/pattern 


n 


!<cmd> Or :!<cmd> 


v 
ai 
mn 
*p 
Ic 


ENVIRONMENT 


E 


f 
bor” 


if 


H elp: display a summary of these commands. If you forget all the othe: commands, remember this one 
Display next k lines of text. D efaults to current screen size. 

Display next k lines of text. D efaults to current screen size Argument becomes new default. 
Display next k lines of text. D efaults to 1. Argument becomes new default. 

Scroll k lines. D efault is current scroll size, initially 11. Argument becomes new default. 
Exit. 

Skip forward k lines of text. D efaults to 1. 

Skip forward k screenfuls of text. D efaults to 1. 

Skip backwards k screenfuls of text. D efaults to 1. 

Go to place whee previous search started. 

Display current line numbe. 

Search for kth occurrence of regular expression. D efaults to 1. 

Search for kth occurrence of last r.e. D efaults to 1. 

Execute <cmd> in a subshell. 

Start up /usr/bin/vi at current line 

Redraw screen. 

Go to kth next file D efaults to 1. 

Go to kth previous file. D efaults to 1. 

Display current filename and line number. 

Repeat previous command. 


more utilizes the following environment variables, if they exist: 


MORE 
SHEL 


TERM 


SEE ALSO 
vi(1), 1ess(1) 


AUTHORS 


L 


This variable may be set with favored options to more. 
Current shell in use (normally set by the shell at login time). 
Specifies terminal type, used by more to get the terminal characteristics necessary to manipulate the screen. 


Eric Shienbrood, UC Berkeley. M odified by Geoff Peck, UCB to add underlining, single spacing. M odified by John 
Foderaro, UCB to add -c and more environment variable. 


HISTORY 


The more command appeared in BSD 3.0. Thisman page documents more version 5.19 (Berkeley 29 June 1988), which is 
currently in use in the Linux community. D ocumentation was produced using several other versions of the man page, and 
extensive inspection of the source code 


Linux 0.98, 25 Decanber 1992 


mrd 


mrd— Removean MS-DOS subdirectory 


SYNOPSIS 


mrd [ -v ] msdosdirectory [ msdosdirectories... ] 


DESCRIPTION 
mrd removes a directory from an M S-D OS filesystem. mma will allow the following command-line option: 
v Verbose mode. Display the directory nameas it is removed. 


An error occurs if the directory does not exist or is not empty. 
SEE ALSO 


mtools(1), mmd(1), mdeltree(1) 
Local 


mread 


mread— Read (copy) an MS-DOS fileto UNIX 
SYNOPSIS 


mread [ -tnvmoOsSrRA ] msdosfile unixfile 


mread [ -tnvmoOsSrRA ] msdosfile [ msdosfiles... ] unixdirectory 
DESCRIPTION 

This command is obsolete, and only supplied for backwards compatibility reasons with old scripts. U semcopy instead. 
SEE ALSO 


meopy(1), mtype(1), mtoo1s(1) 


mren 


mren— Rename or move an existing MS-DOS file or subdirectory 


SYNOPSIS 


mren [ -voOsSrRA ] sourcefile targetfile 


mmove [ -voOsSrRA ] sourcefile [ sourcefiles... ] targetdirectory 


DESCRIPTION 
mren renames an existing fileon an MS-DOS filesystem. 
mren will allow the following command-line option: 
voossrrA Verbose mode. Display the new filename if the name supplied isinvalid. 
If the first syntax is used (only one sourcefile), and if the target name doesn’t contain any slashes or colons, the file (or 


subdirectory) will be renamed in the same directory, instead of being moved to the current mca directory as would be the case 
with mmove. Unlike the MS-DOS version of REN, mren can be used to rename directories. 
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BUGS 


Unlike the MS-DOS version of REN, mren can be used to rename directories. 
SEE ALSO 
med(1) 
Local 


mtest 


mtest— T est the mtools configuration files 


SYNOPSIS 


mtes 


DESCRIPTION 


mtest reads the mtools configuration files and prints the cumulative configuration to stdout. T he output can be used asa 
configuration file itself (although you might want to remove redundant clauses). You may use this program to convert old- 
style configuration files into new style configuration files. 


SEE ALSO 


mtools(5) 





Local 


mtools 


mtools— A collection of tools for manipulating M S-D OS files 


SYNOPSIS 
Themtools are 
mattrib— ChangeM S-D OS file attribute flags 
mbadblocks— T est a floppy disk, and mark the bad blocks in the FAT 
med— Change MS-DOS directory 
meopy— Copy MS-DOS files to/from UNIX 
mdel— D detean MS-DOS file 
mdir— Display an MS-DOS directory 
mformat— Add an M S-D OS filesystan to alow-level formatted floppy disk 
mlabel— M akean MS-DOS volumelabel 
mnd— M ake an M S-D OS subdirectory 
mmount— M ount an M S-D OS disk 
mrd— Removean MS-DOS subdirectory 
mmove— M oveor renamean MS-DOS fileor subdirectory 
mren— Renamean existing MS-DOS file 
mtype— D isplay contents of an MS-DOS file 
mtest— T est and display the configuration 


~ 
DESCRIPTION 


mtools iS a public domain collection of programs to allow UNIX systems to read, write, and manipulate fileson an MS-DOS 
filesystem (typically a floppy disk). W here reasonable, each program attenpts to enulate the M S-D OS equivalent command. 
H owever, unnecessary restrictions and oddities of DOS are not emulated. For instance it is possible to move subdirectories 
from one subdirectory to anothe. 

MS-DOS filenames are optionally composed of a drive letter followed by acolon, a subdirectory, and a filename. Filenames 
without a drive letter refer to UN IX files. Subdirectory names can use either the / or \ separator. The use of the \ separator 
or wildcards will require the names to be enclosed in quotes to protect them from the shal. (N ote: Wildcards in U NIX 
filenames should not be enclosed in quotes, because here users want the shell to expand them.) 


DIFFERENCES WITH MS-DOS 


The regular expression “pattern matching” routines follow the U N IX-style rules. For example * matches all MS-DOS files 
in lieu of *.*. The archive, hidden, read-only, and system attribute bits are ignored during pattern matching. 





All options use the - (minus) flag, not / as you'd expect in MS-DOS. 


M ost mtools commands allow multiple filerame parameters, which doesn’t follow MS-DOS conventions, but which is more 
user friendly. 


WORKING DIRECTORY 
Themed command is used to establish the device and the current working directory (rdative to the M S-D OS filesysten); 
otherwise, the default is assumed to bea:/. However, unlikeM S-DOS, thereis only one working directory, and not one pe’ 
drive. 


VFAT-STYLE LONG FILENAMES 


This version of mtools supports V FAT -style long filenames. If a UNIX filenameis too long to fit in ashort DOS name, it is 
stored asaVFAT long name, and a companion short nameis generated. This short nameis what you see when you examine 
the disk with apre7.0 version of DOS. The following table shows some examples of short names: 





UNIX Name MS-DOS Name Reason for the Change 
thisisatest THISISAT Filename too long 
alain.knaff ALAIN. KNA Extension too long 
prn.txt XRN. TXT PRN isadevicename 
.abe X.ABC N ull filename 
hot+cold HOTXCOLD Illegal character 


Theinitial U N IX-style filename (whether long or short) is also called primary name, and the derived short nameis also called 
secondary name. 


Example: 
mcopy /etc/motd a:Reallylongname 


mtools createsa VFAT entry for Reallylongname, and USeS REALLYLO aS a Short name Reallylongname is the primary name, and 
REALLYLO is the secondary name. 


In this example: 
copy /etc/motd a:motd 


motd fits into the D OS filename limits. mtoo1s doesn’t need to derivate another name. motd isthe primary name, and there is 
no secondary name. 


In anutshdl: The primary name is the long name, if one exists, or the short name if there isno long name 
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NAME CLASHES 


When writing a file to disk, its long name (primary name) or short name may collide with a already existing file or 
directory. T his may happen for all commands that create new directory entries: mcopy, mmd, mren, mmove, mwrite, and mread. 


W hen aname clash happens, mtools asks you what it should do. It offers several choices: 


overwrite O verwrites the existing file. It isnot possible to overwrite a directory with afile 
rename Renames the newly created file mtoo1s will prompt for the new filename. 

autorename Renames the newly created file mtoo1s will chose aname by itsdf, without prompting. 
skip Gives up on thisfile, and moves on to the next (if any). 


To choose an option, type its first letter at the prompt. If you use a lowercase letter, the option applies for this file only; if 
you use an uppercase letter, the option applies to all files. 


You may also choose options (for all files) on the command line when invoking mtools: 


-0 O verwrites primary names by default 

-0 O verwrites secondary names by default 

-r Renames primary name by default 

-R Renames secondary name by default 

-a Autorenames primary name by default 

“A Autorenames secondary name by default 
-s Skips primary name by default 

-§ Skips secondary name by default 

-m Asks user what to do with primary name 
-M Asks user what to do with secondary name 


By default, the user is prompted if the primary name clashes, and the secondary nameis autorenamed. 
If anameclash occursin aUNIX directory, mtools only asks whether to overwrite the file or to skip it. 


CASE SENSITIVITY OF THE VFAT FILESYSTEM 


TheVFAT filesystem is able to remember the case of the filenames. H owever, filenames that differ only in case are not 
allowed to coexist in the same directory. For example if you store a file called LongFileName on aVFAT filesystem, mdir will 
show this file as LongFileName, and not aS Longfilename. H owever, if you then try to add LongFilename to the same directory, 
it will be refused, because case isignored for clash checks. 


TheVFAT filesystem allows the storing of the case of a filenamein the attribute byte, if all letters of the filename are the 
same case, and if all letters of the extension are the same case too. mtools uses this information when displaying the files, and 
also to generate the UNIX when mcopying to aU NIX directory. T his may have unexpected results when applied to files 
written using a pre-7.0 version of DOS; indeed, these filenames map to all uppercase T his is different from the behavior of 
the old version of mtools, which used to generate lowercase U NIX filenames. 


XDF DISKS (LINUX ONLY) 


X df isa high-capacity format supported by 0 S/2. It can hold 1,840KB per disc. That's not very high compared to the best 
2m formats, but its main advantage is that it is fast: 600 milliseconds per track. T hat’s faster than the good old 21 sector 
format, and almost as fast as the standard 18 sector format. In order to access these disks, set theuse_xdf variable for the 
drive. See mtoo1s(5) for details on how to do this. Fast X df access is only available for kernds more recent than 1.1.34. 


CAUTION 


Attention distributors: If mtoo1s is compiled on Linux, on a kernel more recent than 1.3.34, it won’t run on an older 
kernd. H owever, if it has been compiled on an older kernel, it will still run on anewer kernel, except that Xdf access is 


~ & 


slower. It is recommended that distribution authors only include mtools binaries compiled on kernels older than 1.3.34 
until 2.0 comes out. W hen 2.0 isout, mtoo1s binaries compiled on newer kernels may (and should) bedistributed. mtoo1s 
binaries compiled on kerne’s older than 1.3.34 won't run on any kernel 2.1 or later. 


EXIT CODES 


All the mtools commands return @ on success, 1 on utter failure, or 2 on partial failure. All the mtools commands perform a 
few sanity checks before going ahead, to make sure that the disk isindeed an M S-D OS disk (as opposed to, say, an ext2 or 
minix disk). These checks may reject partially corrupted disks, which might otherwise still be readable. To avoid these 
checks, set the MTOOLS_SKIP_CHECK environmental variable. 


SEE ALSO 


mattrib(1), mbadblocks(1), mcd(1), mde1(1), mformat(1), mmove(1), mrd(1), mren(1), mtype(1), mcopy(1), mdir(1), mlabe1(1), 
mmd(1), mmount(1) 


BUGS 


An unfortunate side effect of not guessing the proper device (when multiple disk capacities are supported) isan occasional 
error message from the device driver. T hese can be safely ignored. 


The fat checking code chokes on 1.72M B disks mformatted with pre 2.0.7 mtools. Set the environmental variable 
MTOOLS_FAT_COMPATIBILITY to bypass the fat checking. 


The support for non-Linux OS variants has not been tested for along time. It may contain bugs, or even not work at all. 
Local 


mtvtoppm 


mtvtoppm— Convert output from the MTV or PRT ray tracers into a portable pixmap 


SYNOPSIS 


mtvtoppm [mtvfile] 


DESCRIPTION 
mtvtoppm reads an input filefrom M ark Van DeWetteing’s MTV ray tracer and produces a portable pixmap as output. 
ThePRT ray tracer also produces this format. 


SEE ALSO 
ppm(5) 
AUTHOR 
Copyright © 1989 by J ef Poskanzer 
2 February 1989 


mtype 


mtype— D isplay contents of an MS-DOS file 
SYNOPSIS 


mtype [ -ts ] msdosfile [ msdosfiles... ] 


Part |: User Commands 


DESCRIPTION 
mtype displays the specified M S-D OS file on the screen. 
mtype Will allow the following command-line options: 
t Text file viewing. mtype will translate incoming carriage return/line feeds to line feeds. 
s Strip high bit. mtype will strip the high bit from the data. 


MS-DOS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the names to be enclosed in quotes to protect them from the shel. 


Themed command may be used to establish the device and the current working directory (rdative to MS-DOS); otherwise, 
the default isa:/. 


mtype returns @ on success, 1 on utter failure, or 2 on partial failure. 


SEE ALSO 
med(1), mread(1) 


BUGS 


Allows multiple arguments, which does not follow the MS-DOS convention. 
Local 


mv 


mv— Rename files 


SYNOPSIS 


mv [options] source dest 
mv [options] source... directory 


Options: 


[-bfiuv] [-S backup-suffix] [-V {numbered,existing,simple}] [--backup] [--force] 
[--interactive] [--update] [--verbose] [--suffix=backup-suffix] 
[--version-control={numbered,existing,simple}] [--help] [--version] 


DESCRIPTION 


This manual page documents the GN U version of mv. If the last argument names an existing directory, mv moves each other 
given file into a file with the same name in that directory. O therwise, if only two files are given, it movesthefirst onto the 
second. It isan error if the last argument is not a directory and more than two files are given. It can move only regular files 
across filesystems. If a destination fileis unwritable the standard input isatty, and the -f or --force option is not given, mv 
prompts the user for whether to overwrite the file | f the response does not begin with y or y, thefileis skipped. 


OPTIONS 

-b, --backup M ake backups of files that are about to be removed. 

-f, --force Remove existing destination files and never prompt the user. 

-i, --interactive Prompt whether to overwrite each destination file that already exists. If the response does 
not begin with y or y, thefileis skipped. 

-u, --update Do not move anondirectory that has an existing destination with the same or newer 
modification time 

-v, --verbose Print the name of each file before movingit. 

--help Print a usage message on standard output and exit successfully. 


--version Print version information on standard output, then exit successfully. 


-S, --suffix backup-suffix The suffix used for making simple backup files can be set with the sImPLE_BACKUP_SUFFIX 
environment variable, which can be overridden by this option. If neither of thoseis given, 
the default is ~, as it isin Emacs. 

-V, --version-control The type of backups made can be set with the versIon_conTROL environment variable, which 

{numbered, existing, simple} can be overridden by this option. If verston_conTROL iSnot set and this option is not given, 
the default backup type is existing. T he value of the veRSION_CONTROL environment variable 
and the argument to this option are like the GN U Emacs version-control variable they 
also recognize synonyms that are more descriptive. 

The valid values are the following (unique abbreviations are accepted): 
t OF numbered --Always make numbered backups. 


nil OF existing--M akenumbered backups of files that already have then, simple backups of 
the others. 


never OF simple— Always make simple backups. 


GNU FileUtilitie 
mwrite 
mwrite— Low-level write (copy) aU NIX fileto MS-DOS 
SYNOPSIS 
mwrite [ -tnvmoOsSrRA ] unixfile msdosfile 
mwrite [ -tnvmoOsSrRA ] unixfile [ unixfiles... ] msdosdirectory 
DESCRIPTION 
This command is obsolete and only supplied for backward compatibility reasons with old scripts. Use mcopy instead. 
SEE ALSO 
meopy(1), mtools(1) 
Local 


name 


namei— Follow a pathname until a terminal point is found 


SYNOPSIS 


namei [-mx] pathname [ pathname ... ] 


DESCRIPTION 
namei uses its arguments as pathnames to any type of UN IX file (symlinks, files, directories, and so forth). namei then follows 
each pathname until a terminal point is found (afile directory, char device, and so on). If it finds a symbolic link, the user 
shows the link, and starts following it, indenting the output to show the context. 
This program is useful for finding too many levels of symbolic links problems. 
For each line output, namei outputs the following characters to identify the file types found: 
f: The pathname the user is currently trying to resolve 
d Directory 
1 Symbolic link (both the link and its contents are output) 
s Socket 
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b Block device 

c Character device 
Regular file 

2 An error of somekind 


Namei prints an informative message when the maximum number of symbolic links this system can have has been exceeded. 


OPTIONS 


“x Show mount point directories with ap rather than ad. 
-m Show the mode bits of each file type in the style of 1s(1), for example, rwxr-xr-x. 


AUTHOR 


Roger Southwick (rogers@amadeus.wr.tek.com) 


BUGS 


To be discovered 


CAVEATS 


namei will follow an infinite loop of symbolic links forever. To escape, use SIGINT (usually *c). 
SEE ALSO 
1s(1), stat(1) 
Local 


newaliases 


newaliases— Rebuild the database for the mail aliases file 


SYNOPSIS 


newaliases 


DESCRIPTION 


newaliases rebuilds the random access database for the mail aliases file It must be run each time it is changed in order for the 
change to take effect. 


SEE ALSO 


aliases(5), sendmail(8) 


HISTORY 
The newaliases command appeared in BSD 4.0. 
BSD 4, 30 July 1991 


newgrp 


newgrp— Login to anew group 


SYNOPSIS 


newgrp [ group ] 


nl 337 


DESCRIPTION 


newgrp Changes the group identification of its caller, analogously to login(1). The same person remains logged in, and 
the current directory is unchanged, but calculations of access permissions to files are performed with respect to the new 
group ID. 


If no group is specified, the GID is changed to thelogin GID. 
FILES 


/etc/group 
/etc/passwd 


SEE ALSO 
login(1), group(5) 
Linux 0.99, 9 October 1993 


nl 


nl— N umber lines of files 


SYNOPSIS 


nl [-h header-style] [-b body-style] [-f footer-style] [-p] [-d cc] 
[-v start-number] [-i increment] [-1 lines] [-s line-separator] 

[-w line-no-width] [-n {ln,rn,rz}] [--header-numbering=style] 
[--body-numbering=style] [--footer-numbering=style] 
--first-page=number] [--page-increment=number] [--no-renumber] 
--join-blank-lines=number] [--number-separator=string] 


[ 
[ 
[ 
[ 


--number-width=number] [--number-format={1n,rn,rz}] 
--section-delimiter=cc] [--help] [--version] [file...] 
DESCRIPTION 


This manual page documents the GN U version of ni. nl copies each given file, or the standard input if none are given or 
whe afile named - is given, to the standard output, with line numbers added to some or all of the lines. 


nl considers its input to be composed of logical pages; by default, the line number is reset to 1 at the top of each logical page. 
ni treats all of the input files as a single document; it does not reset line numbers or logical pages between files. 


A logical page consists of three sections: header, body, and footer. Any of the sections can be enpty. Each can be numbered 
in adifferent style from the others. 


The beginnings of the sections of logical pages are indicated in the input file by a line containing nothing except one of the 
following delimiter strings: 


\: start of header 
start of body 
start of footer 


\i\: 
As 
\: 


The two characters from which these strings are made can be changed with an option (see the next subsection), but the 


pattern and length of each string cannot be changed. 


The section ddimiter strings are reolaced by an anpty line on output. Any text that comes before the first section delimiter 
string in the input file is considered to be part of a body section, so afile that does not contain any section ddimiter strings is 
considered to consist of a single body section. 


OPTIONS 


-h, --header-numbering=style See - -footer-numbering 
-b, --body-numbering=style See - -footer-numbering 
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-f, --footer-numbering=style | Sdect thenumbering style for lines in the footer section of each logical page When alineis 
not numbered, the current line number is not incremented, but the line number separator 
character is still prepended to the line. T he styles are 


a N umber all lines 
t N umber only nonempty lines (default for body) 
n N umber no lines (default for header and footer) 
pregexp Number only lines that contain a match for regexp 
-p, --no-renumber Do not reset the line number at the start of a logical page. 
-v, --first-page=number Set the initial line number on each logical page to number (default 1). 


-i, --page-increment=number Increment line numbers by number (default 1). 


-1, --join-blank-lines=number Consider number (default 1) consecutive empty lines to be one logical line for numbering, 
and only number the last one. W here fewer than number consecutive enpty lines occur, do 
not number then. An empty line is one that contains no characters, not even spaces or tabs. 


-s, --number-separator=string Separate the linenumber from the text linein the output with string (default is a tab 
character). 


-w, --number-width=number Use number characters for line numbers (default 6). 
-n, --number-format={1n,rn,rz} Select the linenumbering format: 
ln Left justified, no leading zeros 
rn Right justified, no leading zeros (default) 
rz Right justified, leading zeros 
-d, --section-delimiter=cc Se the two delimiter characters that indicate the beginnings of logical page sections; if only 
oneis given, thesecond remains :. To enter \, use \\. 


--help Print a usage message and exit with a nonzero status. 
--version Print version information on standard output, then exit. 
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nlmconv 


nlmconv— Convert object code into an N LM 


SYNOPSIS 


nlmconv[ -Ibfdname|--input-target=bfdname] [ -Obfdname | 
--output-target=bfdname ] [ -Theaderfile|--header-file=headerfile ] 
[ -V|--version ][--help ] infile outfile 


DESCRIPTION 


nlmconv converts the relocatable object file infile into the N etW are Loadable M odule (NLM ) outfile, optionally reading 
headerfile for NLM header information. For instructions on writing the NLM command file language used in header files, 
see T heN etW areT ool M aker Specification M anual, available from N oval, Inc. nimconv currently works with i386 object files 
in COFF, ELF, ora.out format, and with SPARC object files in ELF or a.out format. nimconv uses the GN U binary file 
descriptor library to read infile. 


OPTIONS 
-I bfdname, Consider the sourcefile’s object format to be bfdname, rather than attempting to deduce it. 
--input-target=bf dname 
-0 bfdname, W rite the output file using the object format bfdname. nimconv infers the output format 
--output-target=bf dname based on the input format, for example, for an i386 input file the output format is 


nlm32-i386. 


" 


-T headerfile, Readsheaderfile for NLM header information. For instructions on writing the NLM 
--header-file=headerfile command file language used in header files, seeT he N &W areT ool M aker Specification 
M anual, available from N oval, Inc. 
-V, --version Show the version number of nimconv and exit. 
-h, --help Show asummary of theoptions to nimconv and exit. 
SEE ALSO 
binutils entry in info; TheGNU Binary Utilities Roland H. Pesch (June 1993). 
COPYING 


Copyright © 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus upport, June 1993 


nm 


nn— List symbols from object files 


SYNOPSIS 


nm [ -a,--debug-syms][-g;--extern-only ][-B ][-C;--demangle ] 

[-D|--dynamic ][-s{--print-armap] [-o0} --print-file-name] 

[-n|--numeric-sort ][-p;--no-sort ][-rj|--reverse-sort ][--size-sort ] 

[ -u;--undefined-only][--help ][--version ][-t radix |--radix=radix ] 

{ -P|-portability ] [ -f format |--format=format ][--target=bfdname ][ objfile ...] 


DESCRIPTION 
GNU nm lists the symbols from object files obj file. If no object files are given as arguments, nm assuMES a. out. 
OPTIONS 
Thelong and short forms of options, shown hereas alternatives, are equivalent. 
-A, -0 
--print-file-name Precede each symbol by the name of the input file where it was found, rather than 
identifying the input file once only before all of its symbols. 
-a, --debug-syms Display debugger-only symbols; normally these are not listed. 
-B Thesame as - -format=bsd (for compatibility with theM IPS nm). 
-C, --demangle D ecode (demangle) low-level symbol names into user-leva names. Besides removing any 
initial underscore prepended by the system, this makes C ++ function names readable. 
-D, --dynamic Display the dynamic symbols rather than the normal symbols. T his is only meaningful for 
dynamic objects, such as certain types of shared libraries. 
-f format Use the output format format , which can bebsa, sysv, Or posix. T he default is bsd. O nly the 
first character of format is significant; it can be either uppercase or lowercase. 
-g, --extern-only Display only external symbols. 


-n, -v, --numeric-sort Sort symbols numerically by their addresses, not alphabetically by their names. 
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-p, --no-sort Don’t bother to sort the symbols in any order; just print then in the order encountered. 

-P, --portability Use the PO SIX.2 standard output format instead of the default format. Equivalent to -f 
posix. 

-s, --print-armap W hen listing symbols from archive members, include the index, a mapping (stored in the 
archive by ar or ranlib) of which modules contain definitions for what names. 

-r, --reverse-sort Reverse the sense of the sort (whether numeric or alphabetic); let the last come first. 

--size-sort Sort symbols by size T he size is computed as the difference between the value of the symbol 


and the value of the symbol with the next higher value T he size of the symbol is printed, 
rather than the value. 


-t radix, --radix=radi x Useradix asthe radix for printing the symbol values. It must be for decimal, o for octal, 
or x for hexadecimal. 
--target=bf dname Specify an object code format other than your systen’s default format. See objdump(1) for 
information on listing available formats. 
-u, - -undefined-only Display only undefined symbols (those external to each object file). 
-V, --version Show the version number of nm and exit. 
--help Show asummary of the options to nm and exit. 
SEE ALSO 
binutils entry in info; TheGNU Binary Utilities Roland H. Pesch (October 1991); ar(1), objdump(1), raniib(1). 
COPYING 


Copyright © 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus support, 5 N ovember 1991 


nntpget 





nntpget— Get Usend articlesfrom a remote N NTP server 

SYNOPSIS 
nntpget [ -d dist ][-f file ][-n newsgroups ][-t timestring ][-o ][-u file ][-v ] host 

DESCRIPTION 
nntpget connects to the N N TP server at the specified host and retrieves articles from it. T he articles are sent to standard 
output. 
The-o flag may be used only if the command is executed on the host where the innd(8) server is running. If this flag is used, 
nntpget connects to the specified remote host to retrieve articles. Any article not present in the local history database is then 


fetched from the remote site and offered to the local server. 
If the -v flag is used with the -o flag, then the M essage-ID of each article will be sent to standard output as it is processed. 


The list of article M essage-D sis normally read from standard input. If the -+ flag is used, then a newnews command is used 
to retrieve all articles newer than the modification date of the specified file. The -u flag is the same except that if thetransfer 
succeeded, the file will be updated with a statistics line, modifying its timestamp so that it can be used in later invocations. If 
the -t flag is used, then the specified ti mest ring iS used as the time and date parameter to the newnews command. 


objcopy 


If either the -+ or -f flags are used, then the -n flag may be used to specify a newsgroup list and the -d flag may beused to 


specify a distribution list. The default is * for all newsgroups, and no distribution list. 
BUGS 


Truncates articles at 512 lines. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews 


SEE ALSO 
innd(8) 


ob} copy 


objcopy— Copy and translate object files 


SYNOPSIS 


objcopy [ -Fbfdname|--target=bfdname ] 

[ -Ibfdname| --input-target=pfdname ] [ -Obfdname | 
--output-target=bfdname ] [ -Rsectionname j 
--remove-section=sectionname ] [ -S; --strip-all ][-g} 
--strip-debug ][-x}--discard-all ][-X} 
--discard-locals][-bbyte;--byte=byte ] [ -iinterleave; 


--interleave=interleave ] [ -v,--verbose][-Vj 
--version ][--help ] infile [ outfile ] 
DESCRIPTION 


TheGNU objcopy utility copies the contents of an object file to another. objcopy usestheGN U BFD library to read and 
write the object files. It can write the destination object file in a format different from that of the source object file. The exact 


behavior of obj copy is controlled by command-line options. 


objcopy creates temporary files to do its translations and deletes them afterward. objcopy uses BFD to do all its translation 
work; it knows about all the formats BFD knows about, and thus is able to recognize most formats without being told 


explicitly. 


infile and outfile are the source and output files, respectively. If you do not specify outfile, objcopy creates a temporary file 


and destructivay renames the result with the name of the input file 


OPTIONS 


-I bfdname, Consider the sourcefile’s object format to be bf dname, rather than attempting to deduce it. 


--input-target=bf dname 


-0 bfdname, W rite the output file using the object format bf dname. 
--output-target=bf dname 


-F bfdname, Usebfdname astheobject format for both theinput and the output file thatis, simply 
--target=bf dname transfer data from source to destination with no translation. 

-R sectionname, Remove the named section from thefile. This option may be given morethan once. N ote 
--remove-section, =sectionname that using this option inappropriately may make the output file unusable 

-S, --strip-all Do not copy relocation and symbol information from the source file 

-g, --strip-debug Do not copy debugging symbols from the sourcefile 

-x, --discard-all Do not copy nonglobal symbols from the source file 


-X, --discard-locals Do not copy compiler-generated local symbols. (T hese usually start with L or .). 
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-b byte, --byte=byte Keep only every byte byte of the input file (header data is not affected). byte can bein the 
range from @ to the interleave-1. This option is useful for creating files to program ROM s. 
It istypically used with an srec output target. 


-i interleave, Only copy one out of every interleave bytes. The oneto copy is selected by the-b or 
--interleave=i nterleave --byte option. T he default is 4. T he interleave is ignored if neither -b nor --byte isgiven. 
-v, --verbose Verbose output: list all object files modified. In the case of archives, objcopy -v lists all 
members of the archive. 

-V, --version Show the version number of objcopy and exit. 
--help Show asummary of theoptions to objcopy and exit. 

SEE ALSO 
binutils entry in info; TheGNU Binary Utilities Roland H. Pesch (June1993). 

COPYING 


Copyright © 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus upport, June 1993 


obj dump 


objdump— D isplay information from object files. 


SYNOPSIS 
objdump [ -a|--archive-headers ][-b\ bfdname | --target= bfdname ] 
[ -d}--disassemble][-D|--disassemble-all ][-f|--file-headers ] 
[ -h|--section-headers | --headers ][-i|--info ][-j\ section 


| --Ssection= section ][-1}--line-numbers ][-m\ machine | -- 
-architecture= machine ][-rj--reloc ][-R|--dynamic-reloc ] 
[ -s|--full-contents ][--stabs ][-t|--syms ][-T| --dynamic- 
syms][-x;--all-headers ][--version ][--help ] objfile ... 


DESCRIPTION 


objdump displays information about one or more object files. The options control what particular information to display. This 
information is mostly useful to programmers who are working on the compilation tools, as opposed to programmers who 
just want thar program to compile and work. 


objfile... are the object files to be examined. When you specify archives, objdump shows information on each of the member 
object files. 
OPTIONS 


W here long and short forms of an option are shown together, they are equivalent. At least one option besides -1 (--1ine- 
numbers) Must be given. 


-a, --archive-headers If any files from obj file are archives, display the archive header information (in a format 
similar to is -1). Besides the information you could list with ar tv, objdump -a shows the 
object file format of each archive menber. 


objcopy 


-b bfdname, Specify the object-code format for the object files to be bf dname. T his may not be necessary; 

--target=bf dname obj dump Can automatically recognize many formats. For example, objdump -b oasys -m vax - 
h fu.o displays summary information from the section headers (-h) of fu.o, which is 
explicitly identified (-m) asa V ax object file in the format produced by O asys compilers. Y ou 
can list the formats available with the -i option. 














-d, --disassemble Display the assembler mnemonics for the machine instructions from obj file. T hisoption 
only disassembles those sections that are expected to contain instructions. 

-D, --disassemble-all Like -d, but disassemble the contents of all sections, not just those expected to contain 
instructions. 

-f, --file-headers Display summary information from the overall header of each filein obj file. 

-h, --section-headers, Display summary information from the section headers of the object file 

--headers 

--help Print asummary of the options to obj dump and exit. 

-i, --info Display alist showing all architectures and object formats available for specification with -b 
OF -m. 

-j name, --section=name Display information only for section name. 

-1, --line-numbers Label the display (using debugging information) with the filename and source line numbers 
corresponding to the object code shown. O nly useful with -d or -p. 

-m machine, Specify the object files obj file arefor architecture machine. You can list available architec- 

--architecture=machine tures using the -i option. 

-r, --reloc Print the relocation entries of the file. If used with -d or -p, the relocations are printed 
interspersed with the disassembly. 

-R, --dynamic-reloc Print the dynamic relocation entries of the file. T hisis only meaningful for dynamic objects, 
such as certain types of shared libraries. 

-s, --full-contents Display the full contents of any sections requested. 

--stabs Display the contents of the .stab, .stab. index, and .stab.excl sectionsfrom an ELF file. 


This is only useful on systems (such as Solaris 2.0) in which .stab debugging symbol-table 
entries are carried in an ELF section. In most other file formats, debugging symbol-table 
entries are interleaved with linkage symbols, and are visible in the --syms output. 


-t, --syms Symbol table. Print the symbol table entries of the file This is similar to the information 
provided by the nm program. 
-T, --dynamic-syms Dynamic symbol table. Print the dynamic symbol table entries of the file T his is only 


meaningful for dynamic objects, such as certain types of shared libraries. This is similar to 
the information provided by the nm program when given the -p (- -dynamic) option. 


--version Print the version number of obj dump and exit. 
-x, --all-headers Display all available header information, including the symbol table and relocation entries. 
Using -x is equivalent to specifying all of -a -f -h -r -t. 
SEE ALSO 
binutils entry in info; TheGNU Binary Utilities Roland H. Pesch (October 1991); nm(1). 
COPYING 


Copyright © 1991 Free Software F oundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus support, 5 N ovember 1991 
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oclock 


oclock— Round X clock 


SYNOPSIS 
oclock [-option ... ] 
DESCRIPTION 
oclock Simply displays the current time on an analog display. 
OPTIONS 
-fg color Choose a different color for both hands and the jewel on the clock 
-bg color Choose a different color for the background. 
-jewel color Choose a different color for thejewd on the clock. 
-minute col or Choose a different color for the minute hand of the clock. 
-hour color Choose a different color for the hour hand of theclock. 


-backing {WhenMapped | Sdect an appropriate leve of backing store. 
Always NotUseful} 





-geometry geometry D efine the initial window geometry; see x(1). 

-display display Specify the display to use; see x(1). 

-bd color Choosea different color for the window border. 

-bw width Choose a different width for the window border. As the Clock widget changes its border around 
quite a bit, this is most usefully set to zero. 

-shape Cause the clock to use the Shape extension to create an oval window. T hisis the default unless the 
shapeWindow resource is set to false. 

-noshape Cause the clock to not reshape itself and ancestors to exactly fit the outline of the clock. 

-transparent Cause the clock to consist only of the jewel, the hands, and the border. 

COLORS 


If you would like your clock to be viewable in color, include the following in the #ifdef coLor section you read with xrab: 


*customization: -color 


This will cause oclock to pick up the colors in the app-defaults color customization file: <xRoot>/1ib/X11/app-defaults/ 
Clock-color. The default colors are 


Clock*Background Gray 

Clock*BorderColor Light blue 

Clock*hour Ydlow 

Clock* jewel Ydlow 

Clock*minute Ydlow 
SEE ALSO 

x(1), X Toolkit documentation 
AUTHOR 


Keith Packard, MIT X Consortium 
X Version 11 Release 6 


od 


od— Dump files in octal and other formats 


SYNOPSIS 


od [-abcdfhiloxv] [-s[bytes]] [-w[bytes]] [-A radix] [-j bytes] [-N bytes] 
[-t type] [--skip-bytes=bytes] [--address-radix=radix] [--read-bytes=bytes] 
[--format=type] [--output-duplicates] [--strings[=bytes]] [--width[=bytes]] 
[--traditional] [--help] [--version] [file...] 


DESCRIPTION 


This manual page documents the GN U version of od. od writes to the standard output the contents of the given files, or of 
the standard input if the name - is given. Each lineof the output consists of the offset in the input file in the leftmost 
column of each line, followed by one or more columns of data from the file, in a format controlled by the options. By 
default, od prints the file offsets in octal and the file data as two-byte octal numbers. 


OPTIONS 
-A, --address-radix=r adi x Sdect the basein which file offsets are printed. radi x can be one of the following: 
d Decimal 
) O ctal 
x H exadecimal 


n N one(do not print offsets) 
The default is octal. 


-j, --skip-bytes=byt es Skip bytes input bytes before formatting and writing. If bytes begins with ox or ox, it is 
interpreted in hexadecimal; otherwise, if it begins with @, in octal; otherwise, in decimal. 
Appending b multiplies it by 512, k by 1024, and m by 1048576. 


-N, --read-bytes=bytes Only output up to bytes bytes of each input file. Any prefixes and suffixes on bytes are 
interpreted as for the -j option. 
-t, --format=type Select the format in which to output the file data. type isa string of one or more of the 


following type indicator characters. If you include more than onetype indicator character in 
asingletype string or use this option more than once, od writes one copy of each output 
line using each of the data types that you specified, in the order that you specified. 


a Named character 

c ASCII character or backslash escape 
d Signed decimal 

f Floating point 

0 Octal 

u Unsigned decimal 

x H exadecimal 


Except for types a and c, you can specify the number of bytes to use in interpreting each 
number in the given data type by following the type indicator character with a decimal 
integer. Alternately, you can specify the size of one of the C compilers built-in data types by 
following the type indicator character with one of the following characters. For integers (a, 


0, u, x)! 

C char 
S short 
I int 

L long 
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-v, --output-duplicates 


-s, --strings[=bytes ] 


-w, --width[=bytes ] 


--help 


--version 


For floating point (+f): 


F float 
D double 
L ong double 


Output consecutive lines that are identical. By default, when two or more consecutive 
output lines would be equal, od outputs only the first line, and puts just an asterisk on the 
following line to indicate that identical lines have been elided. 

Instead of thenormal output, output only string constants in the input, which are a run of 
at least bytes ASCII graphic (or formatting) characters, terminated by anu. If bytes is 
omitted, it defaults to 3. 

Thenumber of input bytes to format per output line It must be a multiple of the least 
common multiple of the sizes associated with the specified output types. If bytes is omitted, 
it defaults to 32. If this option is not given, it defaults to 16. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 





The next several options map the old, pre-PO SIX format specification options to the corresponding PO SIX format specs. 
GNU od accepts any combination of old- and new-style options. F ormat specification options accumulate. 


--traditional 


passwd 


passwd— C hange password 


SYNOPSIS 


passwd [ name ] 


Output as named characters. Equivalent to -t a. 

Output as octal bytes. Equivalent to -t oc. 

Output as ASCII characters or backslash escapes. Equivalent to -t c. 

Output as unsigned decimal shorts. Equivalent to -t u2. 

Output as floats. Equivalent to -t fr. 

Output as hexadecimal shorts. Equivalent to -t x2. 

Output as decimal shorts. Equivalent to -t a2. 

Output as decimal longs. Equivalent to -t a4. 

Output as octal shorts. Equivalent to -t 02. 

Output as hexadecimal shorts. Equivalent to -t x2. 

Recognize the pre-PO SIX nonoption arguments that some older versions of od accepted. 
The following syntax: 
od --traditional [file] [[+]offset[.][b] [[+]l abel [.][b]]] 

can be used to specify at most one file and optional arguments specifying an offset and a 
pseudo-start address, | abel . By default, offset isinterpreted as an octal number specifying 
how many input bytes to skip before formatting and writing. T he optional trailing decimal 
point forces the interpretation of of fset asadecimal number. If no decimal is specified and 
the offset begins with ex or ox, it isinterpreted as a hexadecimal number. If thereis a trailing 
b, the number of bytes skipped will be offset multiplied by 512. The! abel argument is 
interpreted just like offset , but it specifies an initial pseudo- address. T he pseudo addresses 
are displayed in parentheses following any normal address. 





GNU Tet Utilitie 


paste 347 


DESCRIPTION 


passwd changes the specified user’s password. O nly the superuser is allowed to change other users’ passwords. If the user is 
not root, then the old password is prompted for and verified. 


A new password is prompted for twice, to avoid typing mistakes. U nless the user is the superuser, the new password must 
have more than six characters, and must have ather both uppercase and lowercase letters, or nonletters. Some passwords that 
are similar to the user’s name are not allowed. 


FILES 


/etc/passwd 
/etc/shells 


SEE ALSO 
chsh(1), chfn(1) 


BUGS 
A password consisting of all digits is allowed. 
N o warnings are printed if the superuser chooses a poor password. 
The-# and -s options are not supported. 


AUTHOR 
Peter O rbaek (poe@daimi.aau.dk) 
Linux 1.0, 22 June1994 


paste 


paste— M evge lines of files 


SYNOPSIS 
paste [-s] [-d delim-list] [--serial] [--delimiters=delim-list] [--help] 
[--version] [file...] 

DESCRIPTION 


This manual page documents the GN U version of paste. paste prints lines consisting of sequentially corresponding lines of 
each given file, separated by tabs, terminated by anewline. If no files are given, the standard input is used. A filename of - 
means standard input. 


OPTIONS 


-s, --serial Paste the lines of onefile at atime rather than oneline from each file. 


-d, --delimiters delim-list Consecutively use the characters in delim-1ist instead of Tas to separate merged lines. 
When delim-list is exhausted, start again at its beginning. 


--help Print ausage message and exit with anonzevo status. 
--version Print version information on standard output, then exit. 


GNU Tet Utilitie 
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pomclean 

pbmclean— Flip isolated pixels in portable bitmap 
SYNOPSIS 

pbmclean [-connect] [pbmfile] 
DESCRIPTION 


pbmclean reads a portable bitmap as input and outputs a portable bitmap with every pixel that hasless than connect identical 
neighbors inverted. ppmclean can be used to clean up “snow” on bitmap images. 


SEE ALSO 
pbm(5) 


AUTHOR 
Copyright © 1990 by Angus Duggan. Copyright © 1989 by J ef Poskanzer. 
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this 
permission notice appear in supporting documentation. T his software is provided “as is’ without express or implied 
warranty. 


pbmfilters 


pbmfilters— List of all programsin the PBM Plus package 


DESCRIPTION 


anytopnm 


asciitopgm 


atktopbm 


bioradtopgm 


bmptoppm 


brushtopbm 


cmuwmtopbm 


fitstopnm 


fstopgm 


g3topbm 


gemtopbm 


giftopnm 


gouldtoppm 


hips 
hpced 
icon 
ilbm 


opgm 
oppm 
opbm 
oppm 


imgtoppm 


lispmtopgm 


macp 





opbm 


mgrtopbm 


mtvtoppm 


Attempt to convert an unknown type of image file to a portable anymap 
Convert ASCII graphics into a portable graymap 

Convert Andrew T oolkit raster object to a portable bitmap 
Convert a Biorad confocal file into a portable graymap 

Convert aBM P file into a portable pixmap 

Convert a doodle brush file into a portable bitmap 
ConvertaCMU window manager bitmap into a portable bitmap 
Convert aFITS fileinto a portable anymap 

Convert a U senix FaceSaver file into a portable graymap 

Convert a Group 3 fax file into a portable bitmap 

Convert aGEM IMG fileinto a portable bitmap 

Convert aGIF file into a portable anymap 

Convert Gould scanner file into a portable pixmap 

Convert aH IPS file into a portable graymap 

Convert a Photo-CD file into a portable pixmap 

Convert a Sun icon into a portable bitmap 

Convert an ILBM fileinto a portable pixmap 

Convert an IM G-whatnot file into a portable pixmap 

Convert a Lisp machine bitmap file into PGM format 

Convert aM acPaint file into a portable bitmap 

Convert an MGR bitmap into a portable bitmap 

Convert output from the MTV or PRT ray tracers into a portable pixmap 


pbmclean 
pbmlife 
pbmmake 
pbmmask 
pbmpscale 
pbmreduce 
pbmtext 
pbmto10x 
pbmto4425 
pbmtoascii 
pbmtoatk 
pbmtobg 
pbmtocmuwm 
pbmtoepsi 
pbmtoepson 
pbmtog3 
pbmtogem 
pbmtogo 
pbmtoicon 
pbmtolj 
pbmto1nd3 
pbmtolps 
pbmtomacp 
pbmtomgr 
pbmtopgm 
pbmtopi3 
pbmtopk 
pbmtoplot 
pbmtoptx 
pbmtox10bm 
pbmtoxbm 
pbmtozinc 
pbmupc 
pextoppm 
pgmbentley 
pgmcrater 
pgmedge 
pgmenhance 
pgmhist 
pgmkernel 
pgmnoise 
pgmnorm 
pgmoil 
pgmramp 
pgmtexture 
pgmtofs 


Flip isolated pixels in portable bitmap 

Apply C onway’s Rules of Life to a portable bitmap 

Create a blank bitmap of a specified size 

Create a mask bitmap from a regular bitmap 

Enlarge a portable bitmap with edge smoothing 

Read a portable bitmap and reduceit N times 

Render text into a bitmap 

Convert a portable bitmap into Gemini 10X printer graphics 
Display PBM imageson an AT&T 4425 terminal 

Convert a portable bitmap into ASCII graphics 

Convert a portable bitmap to Andrew T oolkit raster object 
Convert a portable bitmap into BitG raph graphics 
Convert a portable bitmap into aCMU window manager bitmap 
Convert a portable bitmap into an encapsulated PostScript 
Convert a portable bitmap into Epson printer graphics 
Convert a portable bitmap into a Group 3 fax file 

Convert a portable bitmap into aGEM IMG file 

Convert a portable bitmap into compressed GraphO n graphics 
Convert a portable bitmap into a Sun icon 

Convert a portable bitmap into H P Laser] et format 
Convert portable bitmap to DEC LN 03+Sixel output 
Convert portable bitmap to PostScript 

Convert a portable bitmap into a M acPaint file 

Convert a portable bitmap into an M GR bitmap 

Convert a portable bitmap to portable graymap by averaging areas 
Convert a portable bitmap into an Atari D egas .pi3 file 
Convert a portable bitmap into a packed (PK ) format font 
Convert a portable bitmap into aU NIX piot(5) file 
Convert a portable bitmap into Printronix printer graphics 
Convert a portable bitmap into an X10 bitmap 

Convert a portable bitmap into an X11 bitmap 

Convert a portable bitmap into a Zinc bitmap 

Create a Universal Product C ode bitmap 

Convert aPCX file into a portable pixmap 

Bentleyize a portable graymap 

Create cratered terrain by fractal forgery 

Edge-detect a portable graymap 

Edge-enhance a portable graymap 

Print a histogram of the values in a portable graymap 
Generate a convolution kernel 

Create a graymap made up of white noise 

N ormalize the contrast in a portable graymap 

Turn a portable graymap into an oil painting 

Generate a grayscale ramp 

Calculate textural features on a portable graymap 

Convert a portable graymap to U senix FaceSaver format 











pbmfilters 
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Convert a portable graymap into Lisp machine format 


pgmtolispm 
pgmtopbm 
pgmtoppm 
pgmtoybm 
piitoppm 
pi3topbm 
picttoppm 
pjtoppm 
pktopbm 
pnmalias 
pnmarith 
pnmcat 
pnmcomp 
pnmconvol 
pnmcrop 
pnmcut 
pnmdepth 
pnmenlarge 
pnmfile 
pnmflip 
pnmgamma 
pnmhistmap 
pnmindex 
pnminvert 
pnmmargin 
pnmnifilt 
pnmnoraw 
pnmpad 
pnmpaste 
pnmrotate 
pnmscale 
pnmshear 
pnmsmooth 
pnmtile 
pnmtoddif 
pnmtofits 
pnmtops 
pnmtorast 
pnmtosgi 
pnmtosir 
pnmtotiff 
pnmtoxwd 
ppm3d 
ppmbrighten 
ppmchange 
ppmdim 


Convert a portable graymap into a portable bi 


Colorize a portable graymap into a portable p 
Convert a portable bitmap into a Bennet Yee 
Convert an Atari D egas PI 1 into a portable pi 
Convert an Atari D egas P13 file into a portab 
Convert aM acintosh PICT fileinto aportab 


tmap 
ixmap 
“face” file 
xmap 

e bitmap 
€ pixmap 











Convert an HP Paint) et file into a portable pixmap 
Convert packed (PK) format font into portable bitmap(s) 
Antialias a portable anymap 

Perform arithmetic on two portable anymaps 
Concatenate portable anymaps 

Composite two portable anymap files together 
General mxn convolution on a portable anymap 
Crop a portable anymap 

Cut a rectangle out of a portable anymap 

Change the maxval in a portable anymap 

Read a portable anymap and enlarge it N times 
Describe a portable anymap 

Perform oneor more flip operations on a portable anymap 
Perform gamma correction on a portable anymap 
Draw ahistogram foraPGM or PPM file 

Build a visual index of a bunch of anymaps 

Invert a portable anymap 

Add a border to a portable anymap 

N onlinear filters: smooth, alpha trim mean, optimal 
Force a portable anymap into plain format 

Add borders to portable anymap 

Paste a rectangle into a portable anymap 

Rotate a portable anymap by some angle 

Scale a portable anymap 

Shear a portable anymap by some angle 

Smooth out an image 

Replicate a portable anymap into a specified size 


Convert a portab 
Convert a portab 
Convert portable 
Convert a portab 
Convert a portab 
Convert a portab 
Convert a portab 
Convert a portab 





eanymap to DDIF format 

e anymap into FITS format 

anymap to PostScript 

€ pixmap into a Sun raster file 
eanymap to an SGI image file 

e anymap into a Solitaire format 
eanymap into a TIFF file 

e anymap into an X11 window dump 


Convert two portable pixmap into ared/blue 3D glasses pixmap 
Change an images Saturation and Value from an H SV map 
Change all pixels of one color to anothe’ in a portable pixmap 
Dim a portable pixmap down to total blackness 


ppmdist 


ppmdither 


ppmflash 


ppmforge 


ppmhist 


ppmmake 


ppmmix 


ppmnorm 


ppmntsc 
ppmpat 
ppmquant 


ppmquantall 
ppmqvga 
ppmrelief 


ppmshift 


ppmspread 


ppmtoacad 


ppmtobmp 


ppmtogif 


ppmtoicr 


ppmtoilbm 


ppmtomap 


ppmtomitsu 


ppmtopcx 


ppmtopgm 
ppmtopit 


ppmtopict 
ppmtopj 
ppmtopjx1 


ppmtopuzz 


ppmtorgb3 


ppmtosixel 


ppmtotga 


ppmtouil 


ppmtoxpm 


ppmtoyuv 


ppmtoyuvsplit 


psid 


opgm 


pstopnm 


qrttoppm 


rast 


opnm 


rawtopgm 


rawtoppm 


rgb3 





oppm 


sgitopnm 


sirtopnm 


Simplistic grayscale assignment for machine generated, color images 
Ordered dither for color images 

Brighten a picture up to complete white out 

Fractal forgeries of clouds, planets, and starry skies 

Print a histogram of a portable pixmap 

Create a pixmap of a specified size and color 

Blend together two portable pixmaps 

N ormalize the contrast in a portable pixmap 

M ake a portable pixmap look like it was taken from an Amevican TV show 
M akea pretty pixmap 

Quantizethe colors in a portable pixmap down to a specified number 
Run ppmquant on a bunch of files all at once, so they share acommon colormap 
8-plane quantization 

Run aLaplacian relief filter on a portable pixmap 

Shift lines of a portable pixmanp left or right by a random amount 
D isplace a portable pixmap’s pixels by a random amount 
Convert portable pixmap to AutoCAD database or slide 

Convert a portable pixmap into aBM P file 

Convert a portable pixmap into aGIF file 

Convert a portable pixmap into NCSA ICR format 

Convert a portable pixmap into an ILBM file 

Extract all colors from a portable pixmap 

Convert a portable pixmap to aM itsubishi S340-10 file 

Convert a portable pixmap into aPCX file 

Convert a portable pixmap into a portable graymap 

Convert a portable pixmap into an Atari D egas P11 file 

Convert a portable pixmap into aM acintosh PICT file 

Convert a portable pixmap to an H P Paintjet file 

Convert a portable pixmap into an HP Paintjet XL PCL file 
Convert a portable pixmap into an X11 “puzzle” file 

Separate a portable pixmap into three portable graymaps 
Convert a portable pixmap into DEC sixd format 

Convert portable pixmap into aT rueVision T arga file 

Convert a portable pixmap into aM otif UIL icon file 

Convert a portable pixmap into an X11 pixmap 

Convert a portable pixmap into an Abekas YUV file 

Convert a portable pixmap into three subsampled raw YU V files 
Convert PostScript “image” data into a portable graymap 
Convert a PostScript file into a portable anymap 

Convert output from the QRT ray tracer into a portable pixmap 
Convert a Sun raster file into a portable anymap 

Convert raw grayscale bytes into a portable graymap 

Convert raw RGB bytes into a portable pixmap 

Combine three portable graymaps into one portable pixmap 
Convert an SGI image file into a portable anymap 

Convert a Solitaire file into a portable anymap 
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sldtoppm Convert an AutoCAD slide file into a portable pixmap 
spctoppm Convert an Atari compressed Spectrum file into a portable pixmap 
spottopgm Convert SPOT satellite images to Portable G raymap format 
sputoppm Convert an Atari uncompressed Spectrum file into a portable pixmap 
tgatoppm Convert TrueVision T arga file into a portable pixmap 
tifftopnm Convert aTIFF file into a portable anymap 
xbmtopbm Convert an X11 or X10 bitmap into a portable bitmap 
ximtoppm Convert an XIM fileinto a portable pixmap 
xpmtoppm Convert an X11 pixmap into a portable pixmap 
xvminitoppm Convert an XV thumbnail picture to PPM 
xwdtopnm Convert an X11 or X10 window dump file into a portable anymap 
ybmtopbm Convert a Bennet Yee “face” file into a portable bitmap 
yuvplittoppm Convert aY-, U- and V-fileinto a portable pixmap 
yuvtoppm Convert Abekas YU V bytes into a portable pixmap 
zeisstopnm Convert a Zass confocal file into a portable anymap 

SEE ALSO 


anytopnm(1), asciitopgm(1), atktopbm(1), bioradtopgm(1), bmptoppm(1), brushtopbm(1), cmuwmtopbm(1), fitstopnm(1), fstopgm(1), 
g3topbm(1), gemtopbm(1), giftopnm(1), gouldtoppm(1), hipstopgm(1), hpcdtoppm(1), icontopbm(1), ilbmtoppm(1), imgtoppm(1), 
lispmtopgm(1), macptopbm(1), mgrtopbm(1), mtvtoppm(1), ppmclean(1), pbmiite(1), ppmmake(1), pbmmask(1), pbmpscale(1), 
pbmreduce(1), ppmtext(1), pbmto10x(1), pbmto4425(1), pbmtoascii(1), ppmtoatk(1), pbmtobbnbg(1), pomtocmuwm(1), pbmtoepsi(1), 
pbmtoepson(1), pbmtog3(1), pbmtogem(1), ppmtogo(1), pomtoicon(1), pbmto1j(1), pbmto1no3(1), ppmtolps(1), pbmtomacp(1), 
pbmtomgr(1), pomtopgm(1), pomtopi3(1), pbmtopk(1), pbmtoplot(1), pomtoptx(1), pbmtoxtobm(1), pbmtoxbm(1), pomtoybm(1), 
pbmtozinc(1), pbmupc(1), pextoppm(1), pgmbentley(1), pgmcrater(1), pgmedge(1), pgmennance(1), pgmhist(1), pgmkernel(1), 
pgmnoise(1), pgmnorm(1), pgmoil(1), pgmramp(1), pgmtexture(1), pgmtofs(1), pgmtolispm(1), pgmtopbm(1), pgmtoppm(1), 
pittoppm(1), pi3topbm(1), picttoppm(1), pjtoppm(1), pktopbm(1), pnmalias(1), pnmarith(1), pnmcat(1), pnmcomp(1), pnmconvol(1), 
pnmcrop(1), pnmcut(1), pnmdepth(1), pnmeniarge(1), pnmfile(1), pnmflip(1), pnmgamma(1), pnmhistmap(1), pnmindex(1), 
pnminvert(1), pnmmargin(1), pnmnifilt(1), pnmnoraw(1), pnmpad(1), pnmpaste(1), pnmrotate(1), pnmscale(1), pnmshear(1), 
pnmsmooth(1), pnmtile(1), pnmtoddit(1), pnmtofits(1), pnmtops(1), pnmtorast(1), pnmtosgi(1), pnmtosir(1), pnmtotift(1), 
pnmtoxwd(1), ppm3d(1), ppmbrighten(1), ppmchange(1), ppmdim(1), ppmdist(1), ppmdither(1), ppmflash(1), ppmforge(1), 
ppmhist(1), ppmmake(1), ppmmix(1), ppmnorm(1), ppmntsc(1), ppmpat(1), ppmquant(1), ppmquantall(1), ppmqvga(1), ppmreliet(1), 
ppmshift(1), ppmspread(1), ppmtoacad(1), ppmtobmp(1), ppmtogit(1), ppmtoicr(1), ppmtoilbm(1), ppmtomap(1), ppmtomitsu(1), 
ppmtopex(1), ppmtopgm(1), ppmtopit(1), ppmtopict(1), ppmtopj(1), ppmtopjx1(1), ppmtopuzz(1), ppmtorgb3(1), ppmtosixel(1), 
ppmtotga(1), ppmtouil(1), ppmtoxpm(1), ppmtoyuv(1), ppmtoyuvsplit(1), psidtopgm(1), pstopnm(1), qrttoppm(1), rasttopnm(1), 
rawtopgm(1), rawtoppm(1), rgb3toppm(1), sgitopnm(1), sirtopnm(1), sldtoppm(1), spctoppm(1), spottopgm(1), sputoppm(1), 
tgatoppm(1), tifftopnm(1), xomtopbm(1), ximtoppm(1), xpmtoppm(1), xvminitoppm(1), xwdtopnm(1), nybmtopbm(1), 
yuvsplittoppm(1), yuvtoppm(1), zeisstopnm(1) 


AUTHORS 


M any. See the individual manual pages. 
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pbmlife 


pbmlife— Apply Conway's Rules of Lifeto a portable bitmap 


SYNOPSIS 


pbmlife [pbmfile] 


pbmmax [| 
DESCRIPTION 


pbmlife reads a portable bitmap as input, applies the Rules of Life to it for one generation, and produces a portable bitmap as 
output. 


A white pixel in the image is interpreted as a live beastie, and a black pixel as an enpty space 


SEE ALSO 
pbm(5) 


AUTHOR 
Copyright © 1988, 1991 by J & Poskanzer 
21 February 1991 


pbmmake 


pbmmake— Create a blank bitmap of a specified size 


SYNOPSIS 


pbmmake [-white;-black;-gray ] width height 


DESCRIPTION 
pbmmake produces a portable bitmap of the specified width and height. The color defaults to white. 


OPTIONS 


In addition to the usual -white and -black, this program implements -gray. T his givesa simple 50 percent gray pattern with 
1's and 0's alternating. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


pbm(5), ppmmake(1) 
AUTHOR 


Copyright © 1989 by J ef Poskanzer 
22 February 1989 


pbmmask 

pbmmask— Create a mask bitmap from a regular bitmap 
SYNOPSIS 

pbmmask [-expand][pbmfile] 
DESCRIPTION 


pbmmask reads a portable bitmap as input and creates a corresponding mask bitmap and writes it out. 


The color to be interpreted as background is determined automatically. Regardless of which color is background, the mask 
will be white where the background is white and black where thefigure is black. 


Part |: User Commands 


This lets you do amasked paste like this, for objects with a black background: 


pbmmask obj > objmask 
pnmpaste < dest -and objmask <x><y>|pnmpaste -or obj <x><y> 


For objects with a white background, you can eather invert them or add a step: 


pbmmask obj > objmask 
pnminvert objmask | pnmpaste -and obj @ @ > blackback 
pnmpaste < dest -and objmask <x><y>|pnmpaste -or blackback <x><y> 


N ote that this three-step version works for objects with black backgrounds, too, if you don’t care about the wasted time 
You can also use masks with graymaps and pixmaps, using the pnmarith tool. For instance 


ppmtopgm obj.ppm | pgmtopbm -threshold | pbmmask > objmask.pbm 
pnmarith -multiply dest.ppm objmask.pbm > t1.ppm 

pnminvert objmask.pbm | pnmarith -multiply obj.ppm - > t2.ppm 
pnmarith -add t1.ppm t2.ppm 


An interesting variation on thisis to pipe the mask through the pnmsmooth script before using it. T his makes the boundary 
between the two images less sharp. 


OPTIONS 


-expand Expands the mask by one pixel out from the image T his is useful if you want alittle white border around your 
image (A better solution might be to turn the ppmiife tool into a general cellular automaton tool... ) 


SEE ALSO 


pnmpaste(1), pnminvert(1), pbm(5), pnmarith(1), pnmsmooth(1) 
AUTHOR 
Copyright © 1988 by J ef Poskanzer 
8 August 1989 


pbmpscale 


pbmpscale— Enlarge a portable bitmap with edge smoothing 


SYNOPSIS 


pbmpscale N [ pbmfile ] 


DESCRIPTION 


pbmpscale reads a portable bitmap as input and outputs a portable bitmap enlarged N times. Enlargement is done by pixd 
replication, with some additional smoothing of corners and edges. 


SEE ALSO 


pnmenlarge(1), ppmscale(1), pom(5) 


AUTHOR 
Copyright © 1990 by Angus Duggan. Copyright © 1989 by J ef Poskanzer. 


NOTES 


pbmpscale works best for enlargements of 2. Enlargements greater than 2 should be done by as many enlargements of 2 as 
possible followed by an enlargement by the remaining factor. 
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pbmreduce 

pbmreduce— Read a portable bitmap and reduceit N times 
SYNOPSIS 

pbmreduce [-floyd}-fs;-threshold ][-value val ] N [pbmfile] 
DESCRIPTION 


pbmreduce reads a portable bitmap as input, reduces it by a factor of v, and produces a portable bitmap as output. 


pbmreduce duplicates a lot of the functionality of pgmtopbm; you could do something like pnmscale | pgmtopbm, but pbmreduce 
is alot faster. 


pbmreduce can be used to “re-halftone” an image. Say you havea scanner that only produces black and white, not grayscale, 
and it does a terrible job of halftoning (most black-and-white scanners fit this description). O ne way to fix the halftoning is 
to scan at the highest possible resolution, say 300dpi, and then reduce by a factor of three or so using pbmreduce.Y Ou Can even 
correct the brightness of an image, by using the -value flag. 


OPTIONS 


By default, the halftoning after the reduction is done via boustrophedonic Floyd-Steinberg error diffusion; however, the - 
threshold flag can be used to specify simple thresholding. T his gives better results when reducing line drawings. 


The -value flag alters the thresholding value for all quantizations. It should be a real number between 0 and 1. Above 0.5 
means darker images; below 0.5 means lighter. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


pnmenlarge(1), pnmscale(1), pgmtopbm(1), ppm(5) 


AUTHOR 
Copyright © 1988 by J ef Poskanzer 
2 August 1989 


pomtext 


pbmtext— Render text into a bitmap 


SYNOPSIS 
pbmtext [-font fontfile][-builtin fontname][text ] 
DESCRIPTION 


pbmtext takes the specified text, athe a single line from the command line or multiple lines from standard input, and renders 
it into a bitmap. 


OPTIONS 
By default, pbmtext usesa built-in font called bdf (about a 10-point Times Roman font). You can use a fixed-width font by 
specifying -builtin fixed. 


You can also specify your own font with the -font flag. Thefontfile isathe aBDF file from the X Window System or a 
PBM file 


Part |: User Commands 


If thefontfile isaPBM file, it is created in avery specific way. In your window system of choice display the following text 
in the desired (fixed-width) font: 

M",/* ['jpay; M 

[ L"#$%8' ()*+ | 

< ,-./01234567 < 

> 89:;<=>2@ABC > 

@ DEFGHIJKLMNO @ 

PQRSTUVWXYZ[ 

{ \]° ‘abcdefg { 

} hijklmnopqrs } 

~ tuvwxyz{}}>7 

M",/* ['jpay; M 

Do ascreen grab or window dump of that text, using for instance xwd, xgrabsc, OF screen-dump. Convert the result into a 
PBM file If necessary, use pnmcut to remove everything except the text. Finally, run it through pnmcrop to make sure the 
edges are right up against the text. pbmtext can figure out the sizes and spacings from that. 


SEE ALSO 


pbm(5), pnmcut(1), pnmcrop(1) 
AUTHOR 
Copyright© 1993 by J & Poskanzer and George Phillips 
26 Octobe 1993 


pomto10x 


pbmto10x— Convert a portable bitmap into Gemini 10X printer graphics 


SYNOPSIS 


pbmto10x [-h][pbmfile] 


DESCRIPTION 


pbmto1ex reads a portable bitmap as input and produces a file of Gemini 10X printer graphics as output. T he 10X’s printer 
codes are alleged to be similar to the Epson codes. 


N ote that there is no 10xtopbm tool; this transformation is one-way. 


OPTIONS 


The resolution is normally 60H by 72V. If the -h flag is specified, resolution is120H by 144V. You may find it useful to 
rotate landscape images before printing. 


SEE ALSO 
pbm(5) 


AUTHOR 
Copyright © 1990 by Ken Yap1 
January 1990 


pbmtoascii 357 


pomto4425 


pbmto4425— Display PBM images on an AT&T 4425 terminal 
SYNOPSIS 


pbmto4425 [pbmfile] 


DESCRIPTION 


Phmto4425 displaysPBM format imageson an AT&T 4425 ASCII terminal using that terminal’s mosaic graphics character 
set. The program should also work with other VT 100-like terminals with mosaic graphics character sets such astheC. Itoh 
CIT-101, but it has not yet been tested on terminals other than the 4425. 


Pbmto4425 puts the terminal into 132-column mode to achieve the maximum resolution of the terminal. |n this mode the 
terminal has a resolution of 264 columns by 69 rows. T he pixels havean aspect ratio of 1:2.6; therefore, an image should be 
processed before being displayed in amanner such as this: 

pnmscale -xscale 2.6 pnmfile \ 

pnmscale -xysize 264 69 \ 

ppmtopgm \ 

pgmtopbm \ 

pbmto4425 


AUTHOR 
Copyright © 1993 by Robet Pelberg 


-------- & 


pbmtoascil 

pbmtoascii— Convert a portable bitmap into ASCII graphics 
SYNOPSIS 

pbmtoascii [-1x2}-2x4][pbmfile] 
DESCRIPTION 


pbmtoascii reads a portable bitmap as input and produces a somewhat crude ASCII graphic as output. 
N ote that there is no asciitopbm tool; this transformation is one-way. 


OPTIONS 


The -1x2 and -2x4 flags provide two alternate ways for the bits to get mapped to characters. W ith 1x2, the default, each 
character reoresents a group of 1 bit across by 2 bits down. With -2x4, each character represents 2 bits across by 4 bits down. 
With the 1x2 mode you can see the individual bits, so it’s useful for previewing small bitmaps on anongraphics terminal. 
The 2x4 mode lets you display larger bitmaps on a standard 80-column display, but it obscures bit-level details. 2x4 mode is 
also good for displaying graymaps. pnmscale -width 158 ! pgmnorm ! pgmtopbm -thresh Should give good results. 

SEE ALSO 
pbm(5) 


AUTHOR 
Copyright © 1988, 1992 by J & Poskanzer 
20 March 1992 
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pbmtoatk 


pbmtoatk— C onvert portable bitmap to Andrew T oolkit raster object 


SYNOPSIS 


pbmtoatk [pbmfile] 


DESCRIPTION 


pbmtoatk reads a portable bitmap as input and produces an Andrew T oolkit raster object as output. 


SEE ALSO 


atktopbm(1), ppm(5) 


AUTHOR 
Copyright © 1991 by Bill Janssen 
26 Septenber 1991 


pbmtobg 


pbmtobg— Convett a portable bitmap into BitGraph graphics 


SYNOPSIS 
pbmtobg [rasterop][x y]< pbmfile 
DESCRIPTION 


pbmtobg reads a portable bitmap as input and produces BBN BitGraph terminal display pixel data (D PD ) sequence as output. 


The rasterop can be specified on the command line. If this is omitted, 3 (replace) will be used. A position in (x,y) coordi- 
nates can also be specified. If both are given, the rasterop comes first. The portable bitmap is always taken from the standard 


input. 

N ote that there is no bgtopbm tool. 
SEE ALSO 

pbm(5) 
AUTHOR 

Copyright © 1989 by M ike Parker 

16 May 1989 

pbmtocmuwm 

pbmtocmuwm— C onvert a portable bitmap into aC MU window manager bitmap 
SYNOPSIS 

pbmtocmuwm [pbmfile] 
DESCRIPTION 


pbmtocmuwm reads a portable bitmap as input and produces a CMU window manager bitmap as output. 


pbmtoepson 


SEE ALSO 


cmuwmtopbm(1), pbm(5) 
AUTHOR 


Copyright © 1989 by J ef Poskanzer 
15 April 1989 


pomtoepsi 
pbmtoepsi— Convet a portable bitmap into an encapsulated PostScript-style preview bitmap 


SYNOPSIS 


pbmtoepsi [-bbonly][pbmfile] 


DESCRIPTION 


pbmtoepsi reads a portable bitmap as input and produces an encapsulated PostScript-style bitmap as output. The output is 
not a standalone PostScript file it isonly a preview bitmap, which can be included in an encapsulated PostScript file. N ote 
that there is no epsitopbm tool; this transformation is one-way. 


This utility isa part of the pstoepsi tool by Doug Crabill (dgc@cs.purdue.edu). 


OPTIONS 

-bbonly Only create a boundary box, don’t fill it with the image. 
SEE ALSO 

pbm(5), pnmtops(1), psidtopgm(1) 
AUTHOR 

Copyright © 1988 by J ef Poskanzer, modified by Doug Crabill 1992 

1992 

pbmtoepson 

pbmtoepson— C onvert a portable bitmap into Epson printer graphics 
SYNOPSIS 

pbmtoepson [pbmfile] 
DESCRIPTION 


pbmtoepson reads a portable bitmap as input and produces a file of Epson printer graphics as output. 
N ote that there is no epsontopbm tool; this transformation is one-way. 


SEE ALSO 
pbm(5) 


AUTHOR 
Copyright © 1991 by John Tiller (tilleregalois.msfc.nasa.gov) and Je Poskanzer 
4 January 1991 


Part |: User Commands 
pomtog3 


pbmtog3— C onvett a portable bitmap into a Group 3 fax file 


SYNOPSIS 


pbmtog3 [pbmfile] 


DESCRIPTION 


pbmtog3 reads a portable bitmap as output and produces a G roup 3 fax file as input. 


REFERENCES 
The standard for Group 3 fax is defined in CCITT Recommendation T .4. 


BUGS 
Probably. 


SEE ALSO 


g3topbm(1), pbm(5) 


AUTHOR 
Copyright © 1989 by Paul H aeberli (<paule@manray.sgi.com>) 


2 Octobe 1989 


pbmtogem 


pbmtogem— C onvert a portable bitmap into aGEM IMG file 


SYNOPSIS 


pbmtogem [pbmfile] 


DESCRIPTION 


pbmtogem reads a portable bitmap as input and produces a compressed GEM IMG file as output. 


BUGS 


pbmtogem does not support compression of repeated lines. 


SEE ALSO 


gemtopbm(1), ppm(5) 


AUTHORS 
Copyright © 1988 by D avid Beckemeyer and J ef Poskanzer 
11 July 1992 


pomtogo 


pbmtogo— Convett a portable bitmap into compressed GraphO n graphics 
SYNOPSIS 


pbmtogo [pbmfile] 


pbmtolj 
DESCRIPTION 


pbmtogo reads a portable bitmap as input and produces 2D compressed GraphO n graphics as output. Be sure to set up your 
GraphO n with the following modes: 8 bits/no parity; obeys no XON/XOFF; nuts are accepted. T hese are all on the Comm 
menu. Also, remember to turn off tty post processing. N ote that there is no gotopbm tool. 
SEE ALSO 
pbm(5) 
AUTHORS 
Copyright © 1988, 1989 by Je Poskanzer, M ichad H abeler, and Bo Thide 
24 N ovember 1989 


pbmtoicon 
pbmtoicon— Convert a portable bitmap into a Sun icon 
SYNOPSIS 
pbmtoicon [pbmfile] 
DESCRIPTION 
pbmtoicon reads a portable bitmap as input and produces a Sun icon as output. 
SEE ALSO 
icontopbm(1), pbm(5) 
AUTHOR 
Copyright © 1988 by J ef Poskanzer 
31 August 1988 
pbmtol} 
pbmtolj— Convert a portable bitmap into H P Laser] et format 
SYNOPSIS 
pbmtolj [-resolution N][-float][-noreset][pbmfile] 
DESCRIPTION 
pbmtolj reads a portable bitmap as input and produces H P LaseyJ et data as output. 
N ote that there is no 1jtopbm tool. 
OPTIONS 
-resolution Specifies the resolution of the output device in dpi. Typical values are 75, 100, 150, 300. The default is 75. 
-float Suppresses positioning information. The default isto write the sequenceesc a 1 0 E to the output file 
-noreset Prevents pbmto1j from writing the reset sequences to the beginning and end of the output file. 


All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 
pbm(5) 


Part |: User Commands 


AUTHORS 

Copyright © 1988 by J ef Poskanzer and M ichael H aberler. -float and -noreset options added by Wim Lewis 

29 August 1988 

pbmtolnd3 

pbmtolne3— C onvett portable bitmap to DEC LN03+Sixd output 
SYNOPSIS 

pbmtoln@3 [-rltbf] pbmfile 
DESCRIPTION 

pbmtolne3 reads a portable bitmap as input and producesa D EC LN 03+Sixd output file. 
OPTIONS 

-Lnn Usenn asvalue for left margin (default 0). 

-ronn Usenn asvalue for right margin (default 2400). 

-t nn Usenn aS value for top margin (default o). 

-b nin Usenn as value for bottom margin (default 3400). 

-f nin Usenn asvalue for form length (default 3400). 
SEE ALSO 

pbm(5) 
AUTHOR 

Tim Cook, 26 February 1992 

7 May1993 


pbmtolps 


pbmtolps— Convert a portable bitmap to PostScript 


SYNOPSIS 


pbmtolps [ -dpi n ] [ pbmfile ] 


DESCRIPTION 


pbmtolps reads a portable bitmap as input, and outputs PostScript. The output PostScript uses lines instead of the image 
operator to generate a (device dependent) picture that will be imaged much faster. 


The PostScript path length is constrained to be less that 1000 points so that no limits are overrun on the Apple Laserwriter 
and (presumably) no other printers. 


SEE ALSO 
pgmtops(1), ppmtops(1), pbm(5) 


AUTHOR 


George Phillips (<phillips@cs.ubc.ca>) 


pbmtomagr 


pbmtomacp 

pbmtomacp— Convert a portable bitmap into aM acPaint file 
SYNOPSIS 

pbmtomacp [-l left ][-r right ][-b bottom][-t top][pbmfile] 
DESCRIPTION 


pbmtomacp reads a portable bitmap as input. If no input file is given, standard input is assumed. Produces a M acPaint file as 
output. 


The generated file is only the data fork of a picture. You will need a program such aSmevert to generate a M acbinary or a 
BinH ex file that contains the necessary information to identify the fileasaPNTG fileto MacOS. 


OPTIONS 


Left, right, bottom, and top let you define a square into the PBM file, which must be converted. D efault isthe whole file. If 
the file is too large for a M acPaint file the bitmap is cut to fit from (left, top). 


BUGS 


The sourcecode contains comments in a language other than English. 


SEE ALSO 


ppmtopict(1), macptopbm(1), pom(5), mevert(1) 


AUTHOR 
Copyright © 1988 by D ouwe van der Schaaf (... !mcvax! uvapsy! vdschaaf) 


31 August 1988 


pbmtomgr 


pbmtomgr— C onvert a portable bitmap into an M GR bitmap 


SYNOPSIS 


pbmtomgr [pbmfile] 


DESCRIPTION 


pbmtomgr reads a portable bitmap as input and produces an M GR bitmap as output. 


SEE ALSO 


mgrtopbm(1), ppm(5) 


AUTHOR 
Copyright © 1989 by J ef Poskanzer 
24 January 1989 
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pbmtopgm 


pbmtopgm— C onvert portable bitmap to portable graymap by averaging areas 


SYNOPSIS 


pbmtopgm <width><height> [pbomfile] 


DESCRIPTION 


pbmtopgm reads a portable bitmap as input and outputs a portable graymap created by averaging the number of pixels within a 
sample area of width by height around each point. ppmtopgm is similar to a special case of ppmconvol. A ppmsmooth step may be 
needed after ppmtopgm. 


pbmtopgm has the effect of antialiasing bitmaps that contain distinct line features. 


SEE ALSO 
pbm(5) 


AUTHOR 
Copyright © 1990 by Angus D uggan. Copyright © 1989 by Jef Poskanzer. 


NOTES 


pbmtopgm works best with odd sample widths and heights. 


pbmtop13 
pbmtopi3— Convert a portable bitmap into an Atari D egas P13 file 


SYNOPSIS 


pbmtopi3 [pbmfile] 


DESCRIPTION 


pbmtopi3 reads a portable bitmap as input and produces an Atari D egas P13 file as output. 


SEE ALSO 


pi3topbm(1), pom(5), ppmtopi1(1), pittoppm(1) 
AUTHOR 
Copyright © 1988 by D avid Beckeneyer (bat! david) and J ef Poxanzer. 
11 M arch 1990 


pomtopk 


pbmtopk— Convert a portable bitmap into a packed (PK) format font 


SYNOPSIS 
pbmtopk pkfile[.pk] tfmfile[.tfm] resolution [-s designsize] [-p num param...] 
[-C cod-ingscheme] [-F family] [-f optfile] [-c num] [-W width] [-H height] 
[-D depth] [-I ital] [-h horiz] [-v vert] [-x xoff] [-y yoff] [pbmfile]... 


pomtoplot 
DESCRIPTION 


pbmtopk reads portable bitmaps as input and produces a packed (PK) font fileand aTFM (TeX font metric) file as output. 
The resolution parameter indicates the resolution of the font, in dots per inch. If the filevame - is used for any of the 
filenames, the standard input stream (or standard output, where appropriate) will be used. 


OPTIONS 


-s designsize | Seésthedesign size of the font, in T eX’s points (72.27 points to the inch). The default design size is1. The 
TFM parameters are given as multiples of the design size. 

num param... Sets the first num font parameters for the font. T he first seven parameters are the slant, interword spacing, 
interword space stretchability, interword space shrinkability, x-haight, quad width, and post-sentence extra 
space of the font. M ath and symbol fonts may have more parameters, see T heT eXbook for alist of these. 
Reasonable default values are chosen for parameters that are not specified. 


no] 


-C codingscheme Setsthecoding schanecomment in theTFM file. 
-F family Sets the font family comment in the TFM file. 
-f optfile Reads the file opt file, which should contain a line of the form: 


filename xoff yoff horiz vert width height depth ital 

The PBM files specified by the filaaame parameters are inserted consecutively in the font with the 
specified attributes. If any of the attributes are omitted, or replaced with *, a default value will be 
calculated from the size of the bitmap. The settings of the -w, -H, -D, -I, -h, -v, -x, and -y options do not 
affect characters created in this way. T he characte number can be changed by including a line starting 
with =, followed by thenew number. Lines beginning with » or # are ignored. 





-c num Sets the character number of the next bitmap encountered to num. 
-W width Sas theTFM width of thenext character to width (in design size multiples). 
-H height Sets the T FM haght of the next character to hei ght (in design size multiples). 
-D depth Ses theTFM depth of the next character to depth (in design size multiples). 
-Lita Sets the italic correction of the next character to ita! (in design size multiples). 
-h horiz Sets the horizontal escapement of the next character to horiz (in pixels). 
“Vv ver Sets the vertical escapement of the next character to vert (in pixels). 
“x xof Sets the horizontal offset of the next character to xoff (in pixels). 
-y yor Sets the vertical offset of the next character to yott (in pixds, from the top row). 
SEE ALSO 
pktopbm(1), pbm(5) 
AUTHOR 


Adapted from T om Rokicki’s pxtopk by Angus D uggan (ajcd@des.ed.ac.uk). 
6 August 1990 


pomtoplot 


pbmtoplot— Convert a portable bitmap into aUN IX piot(5) file 


SYNOPSIS 


pbmtoplot [pbmfile] 


DESCRIPTION 
pbmtoplot reads a portable bitmap as input and producesa UNIX plot file. 
N ote that there is no plottopbm tool; this transformation is one way. 
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SEE ALSO 
pbm(5), plot(5) 


AUTHOR 
Copyright © 1990 by Arthur D avid O Ison. 
1 September 1990 


pbmtoptx 


pbmtoptx— Convert a portable bitmap into Printronix printer graphics 


SYNOPSIS 


pbmtoptx [pbmfile] 


DESCRIPTION 
pbmtoptx reads a portable bitmap as input and produces a file of Printronix printer graphics as output. 
N ote that there is no ptxtopbm tool; this transformation is one-way. 


SEE ALSO 
pbm(5) 


AUTHOR 


Copyright© 1988 by J ef Poskanzer 
31 August 1988 


pbmtox10bm 


pbmtox1@bm— C onvert a portable bitmap into an X10 bitmap 


SYNOPSIS 


pbmtox1@bm [pbmfile] 


DESCRIPTION 


pbmtox1@bm reads a portable bitmap as input and produces an X10 bitmap as output. This older format is maintained for 
compatibility. 


N ote that there is no x1@bmtopbm tool because xbmtopbm can read both X11 and X10 bitmaps. 


SEE ALSO 


pbmtoxbm(1), xbmtopbm(1), pbm(5) 
AUTHOR 


Copyright© 1988 by J ef Poskanzer. 
31 August 1988 
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pbmtoxbm 


pbmtoxbm— C onvert a portable bitmap into an X11 bitmap 


SYNOPSIS 


pbmtoxbm [pbmfile] 


DESCRIPTION 


pbmtoxbm reads a portable bitmap as input and produces an X11 bitmap as output. 


SEE ALSO 


pbmtox10bm(1), xbmtopbm(1), pom(5) 


AUTHOR 
Copyright © 1988 by J ef Poskanzer. 
31 August 1988 


pgmtoybm 


pgmtoybm— C onvert a portable bitmap into a Bennet Yee “face” file 


SYNOPSIS 


pbmtoybm [pbmfile] 


DESCRIPTION 


pgmtoybm reads a portable bitmap as input and produces as output a file acceptable to the face and xbm programs by Bennet 
Y ee (bsy+@cs.cmu.edu), 


SEE ALSO 

ybmtopbm(1), ppm(5), face(1), face(5), xbm(1) 
AUTHORS 

Copyright © 1991 by J amie Zawinski and J ef Poskanzer. 

6 M arch 1990 

pbmtozinc 

pbmtozinc— Convert a portable bitmap into aZinc bitmap 
SYNOPSIS 

pbmtozinc [pbmfile] 
DESCRIPTION 


pbmtozinc reads a portable bitmap as input and produces a bitmap in the format used by the Zinc Interface Library (ZIL) 
version 1.0 as output. 


SEE ALSO 
pbm(5) 
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AUTHORS 
Copyright © 1988 by J ames D arral M cC auley (jdm5548@diamond.tamu.edu) and J ef Poskanzer. 


2 Novenber 1990 


pbmupc 
pbmupc— C reate a U niversal Product C ode bitmap 


SYNOPSIS 


pbmupce [-sl;-s2] type manufac product 


DESCRIPTION 


pbmupe generates a U niversal Product C ode symbol. T hethree arguments are: a one-digit product type, a five digit manufac- 
turer code, and afivedigit product code For example, 0 72890 00011 isthecodefor H aneken. 


As presently configured, ppmupe produces a bitmap 230 bits wide and 175 bits high. The sizecan be altered by changing the 
defines at the beginning of the program, or by running the output through pnmenlarge or pnmscale. 


OPTIONS 


The-s1 and -s2 flags select the style of UPC to generate. The default, -s1, looks more or less like this: 


15 
eothe style, -s2, puts the product type digit higher up, and doesn’t display the checksum digit: 
HHO 
at | 
SEE ALSO 
pom(5) 
AUTHOR 


Copyright © 1989 by J ef Poskanzer. 
14 March 1989 


pcxtoppm 


pextoppm— Convert aPCX fileinto a portable pixmap 


SYNOPSIS 


pextoppm[pcxfile] 


DESCRIPTION 


pextoppm reads a PC X file as input and produces a portable pixmap as output. 


pgmbentley 


SEE ALSO 


ppmtopex(1), ppm(5) 


AUTHOR 
Copyright © 1990 by M ichael Davidson. 
9 April 1990 


pfbtops 


pfbtops— Translate a PostScript font in PFB format to ASCII 


SYNOPSIS 
pfbtops [ pfb_file ] 
DESCRIPTION 


pfbtops translates a PostScript font in PFB format to ASCII. If pfb_file is omitted, the PFB file will be read from the 
standard input. The ASCII format PostScript font will be written on the standard output. PostScript fonts for MS-DOS are 
normally supplied in PFB format. 


Theresulting ASCII format PostScript font can beused with groff. It must first be listed in /usr/1ib/groff/font/devps/ 
download. 


SEE ALSO 
grops(1) 
Groff Verson 1.09, 6 August 1992 


pgmbentley 


pgmbentley— Bentleyize a portable graymap 


SYNOPSIS 


pgmbentley [pgmfile] 
DESCRIPTION 


pgmbentley reads a portable graymap as input, performs the Bentley Effect, and writes a portable graymap as output. 


The Bentley Effect is described in Beyond Photography by H olzmann, Chapter 4, photo 4. It’s a vertical smearing based on 
brightness. 


SEE ALSO 


pgmoil(1), ppmreliet(1), pgm(5) 
AUTHOR 
Copyright © 1990 by W ilson Bent (whb@hoh-2. att.com). 
11 January 1991 
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pgmcrater 

pgmcrater— Create cratered terrain by fractal forgery 
SYNOPSIS 

pgmcrater [-number n][-height|-ysize s][-width;}-xsize s][-gamma g] 
DESCRIPTION 


pgmcrater Creates a portable graymap that mimics cratered terrain. The graymap is created by simulating the impact of a 
given number of craters with random position and size, then rendering the resulting terrain elevations based on a light source 
shining from one side of the screen. T he size distribution of the craters is based on a power law that results in many more 
small craters than large ones. The number of craters of a given size varies as the reciprocal of the area as described on pages 31 
and 32 of The Sdence Of Fractal | mages, edited by H .O. Patgen and D. Saupe (N ew York: Springer-Verlag, 1988). C ratered 
bodies in the solar system are observed to obey this relationship. The formula used to obtain crater radii governed by this law 
from auniformly distributed pseudorandom sequence was deve oped by Rudy Rucker. 

H igh resolution images with large numbers of craters often benefit from being piped through pnmsmooth. T he averaging 
performed by this process eliminates some of thejagged pixels and lends amdlow “telescopic image” feel to the overall 
picture. 


OPTIONS 
-number n CauseSn Craters to be generated. If no -number specification is given, 50,000 craters will be generated. D on’t 
expect to see them all! For every large crater, there are many, many more tiny ones that tend simply to erode the landscape. 
In general, the more craters you specify, the more realistic the result; ideally, you want the entire terrain to have been 
extensively turned over again and again by cratering. H igh-resolution images containing five to ten million craters are 
stunning but take quite a while to create. 
-height height | Sets theheight of the generated image to hei ght pixels. The default height is 256 pixds. 
-width width Sets the width of the generated image to width pixds. The default width is 256 pixds. 
-xsize width Sets the width of the generated image to width pixds. The default width is 256 pixds. 
-ysize height Sets the height of the generated image to hei ght pixels. The default height is 256 pixds. 
-gamma factor | The specified factor is used to gamma correct the graymap in the same manner as performed by pnmgamma. 
The default value is 1.0, which results in a medium contrast image. Values larger than 1 lighten the image 
and reduce contrast, while values less than 1 darken the image, increasing contrast. 








All flags can be abbreviated to their shortest unique prefix. 
BUGS 


The -gamma option isn’t really necessary because you can achieve the same effect by piping the output from pgmcrater 
through pnmgamma. H owever, pgmcrater performs an internal gamma map anyway in the process of rendering the devation 
array into a graymap, so there's no additional overhead in allowing a user-specified gamma. 


Real craters have two distinct morphologies. pgmcrater simulates only small craters, which are hemispherical in shape 
(regardless of the incidence angle of the impacting body, aslong as the velocity is sufficiently high). Large craters, such as 
Copernicus and T ycho on the moon, havea “walled plain” shape with a cross-section more like: 





I\I\ 
1\ /\ 1\ 
Larger craters should really use this profile, including the central peak, and totally obliterate the preexisting terrain. 
SEE ALSO 


pgm(5), pnmgamma(1), pnmsmooth(1) 
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AUTHOR 


John Walker 

Autodesk SA Avenue des Champs-M ontants 14b 
CH-2074 MARIN 

Suisse/ Schweiz/Svizzera/Svizra/ Switzerland 


Usenet: kelvin@Autodesk.com 
Fax: 038/33 88 15 
Voice 038/33 76 33 


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T his software is provided “as is” without express or implied warranty. 


PLUGWARE! If you like this kind of stuff, you may also enjoy J ames Gleick’s “Chaos— T he Software” for MS-DOS, 
available for $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 M arinship 
W ay, Sausalito, CA 94965, USA. T edephone: 800-688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext 4886. Fax: 
415-289-4718. “C haos— T he Software” includes a more comprehensive fractal forgery generator that creates three- 
dimensional landscapes as wdl as clouds and planets, plus five more modules that explore other aspects of C haos. T he user 
guide of more than 200 pages includes an introduction by J ames Glaick and detailed explanations by Rudy Rucker of the 
mathematics and algorithms used by each program. 


15 October 1991 


pgmedge 
pgmedge— Edge detect a portable graymap 


SYNOPSIS 


pgmedge [pgmfile] 


DESCRIPTION 


pgmedge reads a portable graymap as input, outlines the edges, and writes a portable graymap as output. Piping the result 
through pgmtopbm -threshold and playing with the threshold value will give a bitmap of the edges. 


T he edge detection technique used is to take the Pythagorean sum of two Sobel gradient operators at 90 degrees to each 
other. For more details see D igital | mage Processing by Gonzalez and Wintz, Chapter 7. 


SEE ALSO 
pgmenhance(1), pgmtopbm(1), pgm(5), pom(5) 
AUTHOR 
Copyright © 1991 by] ef Poxanze. 
4 February 1990 


pgmenhance 


pgmenhance— Edge enhancea portable graymap 


SYNOPSIS 


pgmenhance [-N][pgmfile] 
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DESCRIPTION 
pgmenhance reads a portable graymap as input, enhances the edges, and writes a portable graymap as output. 


T he edge enhancing technique is taken from Philip R. Thompson’s xim program, which took it from section 6 of Digital 
H alftones by D ot Diffusion, D. E. Knuth, ACM Transaction on GraphicsVol. 6, No. 4, October 1987, which in turn got it 
from two 1976 papers by J. F. Jarviset. al. 


OPTIONS 
The optional -n flag should bea digit from 1 to 9. 1 is the lowest level of enhancement, 9 is the highest; the default is 9. 


SEE ALSO 
pgmedge(1), pgm(5), pbm(5) 


AUTHOR 
Copyright © 1989 by J ef Poskanzer. 
13 January 1989 


pgmhist 


pgmhist— Print a histogram of the values in a portable graymap 


SYNOPSIS 


pgmhist [pgmfile] 


DESCRIPTION 


pgmhist reads a portable graymap as input and prints a histogram of the gray values. 


SEE ALSO 


pgmnorm(1), pgm(5), ppmhist(1) 


AUTHOR 
Copyright © 1989 by J ef Poskanzer 
28 February 1989 


pgmkernel 


pgmkernel— G merate a convolution kernel 


SYNOPSIS 


pgmkernel [ -weight w ] width [ height ] 


DESCRIPTION 


pgmkernel generates a portable graymap array of Sizewidth x height (Orwidth x width ifheight isnot specified) to be used as 
a convolution file by pnmconvol. T he datain theconvolution array K are computed according to the formula: 


1 


Tee wine * + frei gris * 


Ki) = 
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wherew isa coefficient specified via the -weight flag, andwidth andheight aretheX and Y filter sizes. 
Theoutput PGM file is always written out in ASCII format. 
OPTIONS 


The optional -weight flag should bea real number greater than -1. The default value ise.a. 


BUGS 


The computation time is proportional to width * height. T his increases rapidly with the increase of the kernel size. A better 
approach could beto usea FFT in these cases. 


SEE ALSO 


pnmconvol(1), pnmsmooth(1) 


AUTHOR 
Alberto Accomazzi (alberto@cfa. harvard. edu) 
10 D ecanber 1992 


pgmnoise 


pgmnoise— Create a graymap made up of white noise 


SYNOPSIS 


pgmnoise width height 


DESCRIPTION 


pgmnoise Creates a portable graymap that is made up of random pixds with gray values in the range of @ to PGM_MAXMAXVAL 
(depends on the compilation, eather 255 or 65535). T he graymap has asize of width * height pixels. 


SEE ALSO 
pgm(5) 
AUTHOR 
Copyright © 1993 by Frank N eumann 
16 N ovenber 1993 


pgmnorm— N ormalize the contrast in a portable graymap 
SYNOPSIS 

pgmnorm[-bpercent N | -bvalue N][-wpercent N | -wvalue N][pgmfile] 
DESCRIPTION 


pgmnorm reads a portable graymap as input; normalizes the contrast by forcing the lightest pixels to white, the darkest pixds to 
black, and linearly rescaling the ones in between; and produces a portable graymap as output. 


OPTIONS 


By default, the darkest two percent of all pixds are mapped to black, and the lightest one percent are mapped to white You 
can override these percentages by using the -bpercent and -wpercent flags, or you can specify the exact pixel values to be 
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mapped by using the -bvalue and -wvalue flags. Appropriate numbers for the flags can be gotten from the pgmhist tool. If 
you just want to enhance the contrast, then choose values at elbows in the histogram; for example, if value 29 represents 3 
percent of the image but value 30 represents 20 percent, choose 30 for bvalue. If you want to lighten the image, then set 
bvalue to o and just fiddle with wvalue; similarly, to darken the image, set walue to maxval and play with bvalue. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


pgmhist(1), ppmnorm(1), pgm(5) 
AUTHOR 
Partially based on the fbnorm filter in Michael M auldin’s “Fuzzy Pixmap” package. 
Copyright© 1989 by J ef Poskanzer. 
28 February 1989 


pgmoil 
pgmoil— Turn a portable graymap into an oil painting 


SYNOPSIS 


pgmoil [-n N][pgmfile] 


DESCRIPTION 
pgmoil reads a portable graymap asinput, does an “oil transfer,” and writes a portable graymap as output. 
The oil transfer is described in Beyond Photography by H olzmann, Chapter 4, photo 7. It’s a sort of localized smearing. 


OPTIONS 


The optional -n flag controls the size of the area smeared. T he default value is 3. 


BUGS 


Takes along time to run. 


SEE ALSO 


pgmbentley(1), ppmreliet(1), pgm(5) 
AUTHOR 
Copyright© 1990 by Wilson Bent (wnb@hoh-2. att.com). 
11 January 1991 


ogmramp 


pgmramp— G @erate a grayscale ramp 


SYNOPSIS 


pgmramp -lr;-tb | -rectangle;-ellipse width height 


DESCRIPTION 


pgmramp generates a graymap of the specified size containing a black-to-white ramp. T hese ramps are useful for multiplying 
with other images, using the pnmarith tool. 
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OPTIONS 
-lr A left to right ramp 
-tb A top to bottom ramp 
-rectangle A rectangular ramp 
-ellipse An elliptical ramp 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


pnmarith(1), pgm(5) 
AUTHOR 
Copyright © 1989 by J ef Poskanzer. 
24 N ovenber 1989 


pgmtexture 


pgmtexture— Calculate textural features on a portable graymap 


SYNOPSIS 


pgmtexture [-d d][pgmfile] 


DESCRIPTION 


pgmtexture reads a portable graymap as input. Calculates textural features based on spatial dependence matrices at 0, 45, 90, 
and 135 degrees for adistanced (default = 1). T extural features include 


(1) Angular Second M oment 
(2) Contrast 

(3) Corrdation 

(4) Variance 

(5) Inverse Difference Moment 
(6) Sum Average 

(7) Sum Variance 

(8) Sum Entropy 

(9) Entropy 

(10) Difference V ariance 

(11) Difference Entropy 

(12, 13) Information M easures of C orrelation 


(14) M aximal Correlation Coefficient 
Algorithm taken from “T extural Features for | mage Classification,” IEEE T ransactions on Systems M an, and C ybettinetics, 
R.M. Haralick, K. Shanmugam, and |. D instein, 1973. SM C-3(6):610- 621. 

BUGS 


The program can run incredibly slowly for large images (larger than 64x64) and command-line options are limited. T he 
method for finding the maximal corrdation coefficient, which requires finding the second largest eigenvalue of amatrix Q, 
does not always converge. 


REFERENCES 
|EEE T ransactionson Systems, M an, and Cybertinetics, SM C-3(6):610- 621. 
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SEE ALSO 
pgm(5), pnmcut(1) 
AUTHOR 
Copyright © 1991 by Texas Agricultural Experiment Station, enploye-for-hire of J ames Darrell M cC auley. 
22 August 1991 
pgmtots 
pgmtofs— Convert portable graymap to U senix FaceSaver format 
SYNOPSIS 
pgmtofs [pgmfile] 
DESCRIPTION 
pgmtofs reads a portable graymap as input. Produces U senix FaceSaver format as output. 
FaceSaver is a registered trademark of M eron Computerware Ltd. of Oakland, CA. 
SEE ALSO 
fstopgm(1), pgm(5) 
AUTHOR 
Copyright© 1991 by J ef Poskanzer. 
18 May 1990 


pgmtolispm 
pgmtolispm— Convert a portable graymap into Lisp machine format 


SYNOPSIS 


pgmtolispm [pgmfile] 


DESCRIPTION 
pgmtolispm reads a portable graymap as input and produces a Lisp machine bitmap as output. 
This is the file format read by the tv:read-bit-array-file function on TI! Explorer and Symbolics Lisp machines. 


Given aPGM (instead of aPBM ), amultiplane image will be output. Thisis probably not useful unless you have a color 
Lisp machine. 


M ultiplane bitmaps on Lisp machines are color; but the 1ispm image file format does not include a colormap, so it must be 
treated as a graymap instead. This is unfortunate. 


SEE ALSO 


lispmtopgm(1), pgm(5) 


BUGS 


O utput width is always rounded up to the nearest multiple of 32; this might not always be what you want, but it probably is 
(arrays that are not modulo 32 cannot be passed to the 1ispm B1TBLT function, and thus cannot easily be displayed on the scree). 


Nocolor. 
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AUTHOR 
Copyright © 1991 by J amie Zawinski and J ef Poskanzer. 


6 March 1990 


pgmtopbm 


pgmtopbm— C onvert a portable graymap into a portable bitmap 


SYNOPSIS 


pgmtopbm [-floyd|-fs}-threshold |-hilbert | -dither8} -d8}-cluster3 
1-03; -cluster4|-c4 |-cluster8}-c8][-value val ][-clump size ][pgmfile] 


DESCRIPTION 
pgmtopbm reads a portable graymap as input and produces a portable bitmap as output. 
N ote that there is no pbmtopgm converter because any pgm program can read PBM files automagically. 


OPTIONS 


The default quantization method is boustrophedonic Floyd-Stanberg error diffusion (-floyd or -fs). Also available are 
simple thresholding (-threshold); Bayer’s ordered dither (-dithers) with a 16x16 matrix; and three different sizes of 45- 
degree clustered-dot dither (-cluster3, -cluster4, -clusters). A spacefilling curve halftoning method using theH ilbet 
curve is also available. (-hilbert). 


Floyd-Steinberg will almost always give the best looking results; however, looking good is not always what you want. F or 
instance, thresholding can be used in a pipdine with the pnmconvol tool, for tasks like edge and peak detection. And 
clustered-dot dithering gives a newspaper-like look, a useful special effect. T he -value flag alters the thresholding value for 
Floyd-Steinberg and simple thresholding. It should be a real number between 0 and 1. Above 0.5 means darker images; 
bedow 0.5 means lighter. 





TheH ilbert curve method is useful for processing images before display on devices that do not render individual pixds 
distinctly (like laser printers). T his dithering method can give better results than the dithering usually done by the laser 
printers thenselves. The -clump flag alters the number of pixdsin a clump. This is usually an integer between 2 and 100 
(default 5). Smaller clump sizes smear the image less and are less grainy, but seem to loose some grayscale linearity. Typically, 
aPGM image will have to be scaled to fit on alaser printer page (2400 x 3000 pixels for an A4 300dpi page), and then 
dithered to aPBM imagebefore being converted to a PostScript file A printing pipeline might look something like this: 


pnmscale -xysize 2400 3000 image.pgm | pgmtopbm -hil | pnmtops -scale 0.25 image.ps 
All flags can be abbreviated to their shortest unique prefix. 
REFERENCES 


The only reference you need for this stuff is Digital H alftoning by Robert Ulichney, MIT Press, ISBN 0-262-21009-6. 


TheH ilbert curve space filling method istaken from “D igital H alftoning with Space Filling Curves” by Luiz Velho, 
Computer Graphics Volume 25, N umber 4, proceedings of SIGRAPH ‘91, page 81. |SBN 0-89791-436-8 


SEE ALSO 


pbmreduce(1), pgm(5), pom(5), pnmconvo1(1), pnmscale(1), pnmtops(1) 
AUTHOR 
Copyright © 1989 by J ef Poskanzer. 
26 July 1988 
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pgmtoppm 


pgmtoppm— C olorize a portable graymap into a portable pixmap 


SYNOPSIS 


pgmtoppm colorspec [pgmfile] 
pgmtoppm colorspecl-colorspec2 [pgmfile] 
pgmtoppm -map mapfile [pgmfile] 


DESCRIPTION 


pgmtoppm reads a portable graymap as input, colorizesit by multiplying the gray values by specified color or colors, and 
produces a portable pixmap as output. 


If only one color is specified, black in the PGM file stays black and whitein thePGM file turnsinto the specified color in 
the PPM file If two colors (separated by ahyphen) are specified, then black gets mapped to the first color and white gets 
mapped to the second. 


Thecolor can be specified in five ways: 


m A name, assuming that a pointer to an X11-style color names file was compiled in. 

An X11-style hexadecimal specifier: rgb:r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

An X11-style decimal specifier: rgbi:r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

For backwards compatibility, an old-X 11-style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, OF #rrrrggggbbbb. 
For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (This style was added beforeMIT cameup with thesimilar rgbi style) 


Also, the -map flag lets you specify an entire colormap to be used. The mapfileis just aPPM file; it can be any shape all that 
mattersis the colorsin it and ther order. In this case, black gets mapped to the first color in the mapfile, and white gets 
mapped to the last. 


SEE ALSO 
rgb3toppm(1), ppmtopgm(1), ppmtorgb3(1), ppm(5), pgm(5) 
AUTHOR 
Copyright© 1991 by J ef Poskanzer. 
11 January 1991 


piitoppm 
pi1toppm— Convert an Atari D egas PI 1 into a portable pixmap 


SYNOPSIS 


piltoppm [pilfile] 


DESCRIPTION 


piltoppm reads an Atari D egas PI 1 file as input and produces a portable pixmap as output. 


SEE ALSO 
ppmtopii(1), ppm(5), pi3topbm(1), ppmtopi3(1) 
AUTHORS 
Copyright© 1991 by Steve Baczyk (seb3egte.com) and J & Poskanzer. 
19 July 1990 
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pi3topbm 
pi3topbm— Convert an Atari D egas PI3 file into a portable bitmap 


SYNOPSIS 


pi3topbm [pi 3file] 


DESCRIPTION 


pi3topbm reads an Atari D egas PI3 file as input. Produces a portable bitmap as output. 


SEE ALSO 


pbmtopi3(1), pom(5), pittoppm(1), ppmtopit(1) 


AUTHORS 
Copyright© 1988 by D avid Beckemeyer (bdt!david) and Diomidis D. Spinellis. 
11 M arch 1990 


picttoppm 


picttoppm— Convert aM acintosh PICT file into a portable pixmap 


SYNOPSIS 


picttoppm [-verbose][-fullres][ -noheader][-quickdraw][-fontdirfile] [pictfile] 


DESCRIPTION 


picttoppm reads aPICT file(version 1 or 2) and outputs a portable pixmap. U seful as the first step in converting a scanned 
image to something that can be displayed on UNIX. 


OPTIONS 


-fontdir file M ake thelist of BDF fontsin file available for use by pict-toppm when drawing text. For the format of 
the fontdir file see the “fontdir File Format” subsection. 

-fullres Forceany imagesin the PICT file to be output with at least thar full resolution. A PICT file may indicate 
that a contained image is to be scaled down before output. T his option forces imagesto retain ther sizes 
and prevent information loss. U se of this option disables all PICT operations except images. 


-noheader Do not skip the 512-byte header that is present on all PICT files. This is useful when you have PICT data 
that was not stored in thedata fork of aPICT file 
-quickdraw Execute only pure quickdraw operations. In particular, turn off the interpretation of special PostScript 
printer operations. 
-verbose Turns on verbose mode, which prints a whole bunch of information that only picttoppm hackers really 
care about. 
BUGS 


ThePICT file format isa general drawing format. picttoppm doesnot support all the drawing commands, but it does have 
full support for any image commands and reasonable support for line, rectangle, polygon, and text drawing. It is useful for 
converting scanned images and some drawing conversion. 


Memory is used very liberally with at least six bytes needed for every pixd. Large bitmap PICT files will likely run your 
computer out of memory. 
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fontdir FILE FORMAT 
picttoppm hasa built-in default font and your local installer probably provided adequate extra fonts. You can point picttoppm 
at more fonts that you specify in a font directory file. Each linein the file is ether a comment line which must begin with #, 
or font information. The font information consists of four whitespace separated fidds. The first is the font number, the 
second isthe font sizein pixds, the third isthe font style and the fourth isthenameof aBDF file containing the font. The 
BDF format is defined by the X Window Systen and is not described here. 


The font number indicates the type face. H ere is alist of known font numbers and their faces. 
Chicago 
Application font 
N ew York 
Geneva 
M onaco 
Venice 
London 
Athens 
San Francisco 
Toronto 

1 Cairo 

12 LosAngedes 

20 Times Roman 

21 H elvetica 

22 Courier 

23 Symbol 

24 Taliesin 


+- © ON DODO FO YM = & 


The font style indicates a variation on the font. M ultiple variations may apply to a font and the font styleis the sum of the 
variation numbers, which are 


1 Boldface 

2 Italic 

4 Underlined 
8 Outlined 
16 Shadow 

32 Condensed 
64 Extended 


O bviously, the font definitions are strongly related to the M acintosh. M ore font numbers and information about fonts can 
be found in M acintosh documentation. 


SEE ALSO 


Inside M acintosh volumes 1 and 5, ppmtopict(1), ppm(5) 
AUTHOR 
Copyright ©1993 George Phillips. 
29 November 1991 


pnmalias 


pj toppm 


pjtoppm— Convert an H P Paint) 4 file to a portable pixmap 


SYNOPSIS 


pjtoppm [paintjet ] 


DESCRIPTION 


pjtoppm reads an H P Paintjet file as input and converts it into a portable pixmap. T his was a quick hack to save some trees, 
and it only handles a small subset of the paintjet commands. In particular, it will only handle enough commands to convert 
most raster image files. 


REFERENCES 
HP Paint} & XL Color GraphicsPrinter U ser’s Guide 


SEE ALSO 
ppmtopj(1) 


AUTHOR 
Copyright© 1991 by Christos Zoulas. 
14 July 1991 


pktopbm 
pktopbm— Convert packed (PK) format font into portable bitmap(s) 


SYNOPSIS 


pktopbm pkfile[.pk] [-c num] pbmfile ... 


DESCRIPTION 


pktopbm reads a packed (PK) font file as input and produces portable bitmaps as output. If the filename “-” is used for any of 
the filenames, the standard input stream (or standard output where appropriate) will be used. 


OPTIONS 

-c num Sets the character number of the next bitmap written to num. 
SEE ALSO 

pbmtopk(1), pbm(5) 
AUTHOR 

Adapted from T om Rokicki’s pxtopk by Angus D uggan (ajcd@des.ed.ac.uk). 

6 August 1990 

pnmalias 

pnmalias— Antialias a portable anymap. 
SYNOPSIS 


pnmalias [-bgcolor color ][-fgcolor color ][-bonly][-fonly][-balias][-falias] 
[-weight w][pnmfile] 
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DESCRIPTION 


pnmalias reads a portable anymap as input and applies antialiasing to background and foreground pixels. If the input fileis a 
portable bitmap, the output antialiased image is promoted to a graymap, and a message is printed informing the user of the 


change in format. 


OPTIONS 
-bgcolor colorb, Se the background color to col orb, and the foreground to color to col orf . Pixals with these values 
-fgcolor colorf will be antialiased. By default, the background color is taken to be black, and foreground color is 


assumed to be white The colors can be specified in five ways: 


A name, assuming that a pointer to an X11-style color names file was compiled in. 

An X11-style hexadecimal specifier: rgb:r/g/b, where r, g, and b are each 1- to 4-digit 
hexadecimal numbers. 

An X11-style decimal specifier: rgbi:r/g/b, where r, g, and b are floating-point numbers 
between 0 and 1. 

For backwards compatibility, an old-X 11-style hexadecimal number: #rgb, #rrggbb, 
#rrrgggbbb, OF #rrrrggggbbbb. 

For backwards compatibility, a triplet of numbers separated by commas: r,g,b, wherer, g, 
and b are floating-point numbers between 0 and 1. (T hisstyle was added beforeMIT came 
up with the similar rgbi style) 


N ote that even when dealing with graymaps, background and foreground colors need to be specified in the fashion described 
in the preceding list. In this case, background and foreground pixel values are taken to be the value of the red component for 


the given color. 


-bonly, -fonly Apply antialiasing only to background (-bon1y), or foreground (-fonly) pixds. 

-balias, -falias Apply antialiasing to all pixels surrounding background (-balias), or foreground (-falias) pixds. 
By default, antialiasing takes place only among neighboring background and foreground pixels. 

-weight w Usew asthe central weight for the aliasing filter. w must be a real number in the range 0 <w <1. 


The lower the value of w is, the “blurrier” the output image is. The default isw = 1/3. 


SEE ALSO 


pbmtext(1), pnmsmooth(1), pnm(5) 


AUTHOR 


Copyright© 1992 by Alberto Accomazzi, Smithsonian Astrophysical O bservatory. 


pnmarith 


30 April 1992 


pnmarith— Perform arithmetic on two portable anymaps 


SYNOPSIS 


pnmarith -add;-subtract;-multiply;-difference pnmfilel pnmfile2 


DESCRIPTION 


pnmarith reads two portable anymaps as input, performs the specified arithmetic operation, and produces a portable anymap 
as output. T hetwo input anymaps must be the same width and height. 


The arithmetic is performed between corresponding pixels in the two anymaps, as if maxval waS1.0, black waSo.0, with a 
linear scalein between. Results that fall outside of [o..1) are truncated. 





pnmcomp 


The operator -difference calculates the absolute value of 
pnmarith -subtract pnmfilel pnm-file2 

In other words, no truncation is done. 

All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 


pbmmask(1), pnmpaste(1), pnminvert(1), pnm(5) 


AUTHOR 
Copyright© 1989, 1991 by J e& Poskanzer. Lightly modified by M arca W ijkstra (wijkstra@fwi.uva.n1). 
26 August 1993 


pnmcat 


pnmcat— C oncatenate portable anymaps 


SYNOPSIS 
pnmcat [-white;-black] -leftright;-lr [-jtop;-jbottom] pnmfile pnmfile ... 
pnmcat [-white;-black] -topbottom;-tb [-jleft|-jright] pnmfile pnmfile ... 
DESCRIPTION 
pnmcat reads portable anymaps as input, concatenates than either left to right or top to bottom, and produces a portable 
anymap as output. 


OPTIONS 


If the anymaps are not all the same height (left-right) or width (top-bottom), the smaller ones have to be justified with the 
largest. By default, they get centered, but you can specify one side or the other with one of the -j* flags. So, -topbottom - 
jleft would stack the anymaps on top of each othe, flush with the left edge 


The -white and -black flags specify which color to use to fill in the extra space when doing this justification. If nether is 
specified, the program makes a guess. 


All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 
pnm(5) 


AUTHOR 
Copyright© 1989 by J ef Poskanzer. 
12 M arch 1989 


pnmcomp 


pnmcomp— C omposite two portable anymap files together 


SYNOPSIS 


pnmcomp [-invert][-xoffN] [-yoffN] [-alphapgmfile] overlay [pnm-input ][pnm- output ] 


Part |: User Commands 


DESCRIPTION 
pnmcomp reads in a portable anymap image and puts an overlay upon it, with optional alpha mask. The -alphapgmfile allows 
you to also add an alpha mask file to the compositing process; the range of max and min can be swapped by using the - invert 
option. The -xoff and -yoff arguments can be negative, allowing you to shift the overlay off the top corner of the screen. 
SEE ALSO 
pnm(5) 


AUTHOR 
Copyright© 1992 by D avid K oblas (koblas@mips.com). 
21 February 1989 


pnmconvol 

pnmconvol— General xn convolution on a portable anymap 
SYNOPSIS 

pnmconvol convolutionfile [pnmfile] 
DESCRIPTION 


pnmconvol reads two portable anymapsas input, convolves the second using the first, and writes a portable anymap as output. 


Convolution means replacing each pixel with a weighted average of the nearby pixds. The weights and the area to average are 
determined by the convolution matrix. The unsigned numbers in the convolution file are offset by -maxva1/2 to make signed 
numbers, and then normalized, so the actual values in the convolution file are only relative 


H ereisasample convolution file it does a simple average of the nine immediate neighbors, resulting in a smoothed image 


P2 
33 
18 
10 10 10 
10 10 10 
10 10 10 


To see how this works, do the offset mentioned in the preceding paragraph: 10 - 18/2 gives 1. T he possible range of values is 
from 0 to 18, and after the offset that’s -9 to 9. The normalization step makes the range -1 to 1, and the values get scaled 
correspondingly so they become 1/9— exactly what you want. The equivalent matrix for 5x5 smoothing would have maxval 
50 and be filled with 26. 


The convolution file will usually be a graymap, so that the same convolution is applied to each color component. H oweve,, if 
you want to use a pixmap and do a different convolution to different colors, you can certainly do that. 


SEE ALSO 


pnmsmooth(1), pnm(5) 


AUTHOR 
Copyright© 1989, 1991 by J e& Poskanze. 
13 January 1991 


pnmdepth 


pnmcrop— Crop a portable anymap 
SYNOPSIS 

pnmcrop [-white} -black][-left][-right][-top][-bottom] [pnmfile] 
DESCRIPTION 


pnmcrop reads a portable anymap as input, removes edges that are the background color, and produces a portable anymap as 
output. 


OPTIONS 


By default, it makes a guess as to what the background color is. You can override the default with the -wnite and -black flags. 


The options -1eft, -right, -top and -bottom restrict cropping to the sides specified. T he default isto crop all sides of the 
image. 
All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 


pnmcut(1), pnm(5) 


AUTHOR 
Copyright © 1989 by J ef Poskanzer. 
25 February 1989 


pnmcut 

pnmcut— C ut a rectangle out of a portable anymap 
SYNOPSIS 

pnmcut x y width height [pnmfile] 
DESCRIPTION 


pnmcut reads a portable anymap as input, extracts the specified rectangle, and produces a portable anymap as output. T hex 
and y can be negative in which case they are interpreted relative to the right and bottom of the anymap, respectively. 


SEE ALSO 
pnm(5) 


AUTHOR 
Copyright © 1989 by J ef Poskanzer. 
21 February 1989 


pnmdepth 


pnmdepth— Change the maxval in a portable anymap 


SYNOPSIS 


pnmdepth newmaxval [pnmfile] 
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DESCRIPTION 


pnmdepth reads a portable anymap as input, scales all the pixd values, and writes out the image with the new maxval. Scaling 
the colors down to a smaller maxvai will result in some loss of information. 


Becareful of off-by-oneerrors when choosing the new maxval. For instance, if you want the color values to be five bits wide, 
use a maxval Of 31, not 32. 


SEE ALSO 


pnm(5), ppmquant(1), ppmdither(1) 


AUTHOR 
Copyright © 1989, 1991 by J e& Poskanzer. 
12 January 1991 


pnmenlarge 


pnmenlarge— Read aportable anymap and enlarge it N times 


SYNOPSIS 


pnmenlarge N [pnmfile] 


DESCRIPTION 


pnmenlarge reads a portable anymap as input, replicates its pixelsn times, and produces a portable anymap as output. 





pnmenlarge Can only enlarge by integer factors. T he slower but more general pnmscale can enlarge or reduce by arbitrary 
factors, and pbmreduce can reduce by integer factors, but only for bitmaps. 


If you enlarge by a factor of 3 or more you should probably add a pnmsmooth step; otherwise, you can see the original pixels 
in the resulting image. 


SEE ALSO 


pbmreduce(1), pnmscale(1), pnmsmooth(1), pnm(5) 
AUTHOR 


Copyright © 1989 by J ef Poskanzer. 
26 February 1989 


pnmfile 


pnmfile— D escribea portable anymap 


SYNOPSIS 


pnmfile [pnmfile] ... 


DESCRIPTION 


pnmfile reads one or more portable anymaps as input and writes out short descriptions of the image type size, and so on. 
Thisis mostly for usein shell scripts, so theformat is not particularly pretty. 


SEE ALSO 
pnm(5), file(1) 
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AUTHOR 
Copyright © 1991 by J ef Poskanzer. 


9 January 1991 


pnmflip 
pnmflip— Perform oneor more flip operations on a portable anymap 


SYNOPSIS 


pnmflip [-leftright}-1r][-topbottom| -tb][-transpose} -xy][-rotate9Q;| -r90}-ccw ] 
[-rotate270} -r270|-cw ][-rotate180; -r180][pnmfile] 


DESCRIPTION 


pnmflip reads a portable anymap as input, performs one or more flip operations in the order specified, and writes out a 
portable anymap. 


OPTIONS 


The flip operations available are left for right (-1eftright or -1r); top for bottom (-topbottom or -tb); and transposition (- 
transpose Or -xy).1n addition, somecanned concatenations are available -rotateg90 or -ccw iSequivalent to -transpose - 
topbottom; -rotate270 Or -cw is equivalent to -transpose -leftright; and -rotate180 isequivalent to -leftright -topbottom. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


pnmrotate(1), pnm(5) 


AUTHOR 
Copyright© 1989 by J ef Poskanzer. 





25 July 1989 


pnmgamma 
pnmgamma— Perform gamma correction on a portable anymap 


SYNOPSIS 


pnmgamma value [pnmfile] 
pnmgamma redvalue greenvalue bluevalue [pnmfile] 


DESCRIPTION 
pnmgamma reads a portable anymap as input, performs gamma correction, and produces a portable anymap as output. 


The arguments specify what gamma values) to use A value of 1.0 leaves the image alone, less than 1 darkens it, and greater 
than 1 lightens it. 


SEE ALSO 
pnm(5) 


AUTHOR 
Copyright© 1991 by Bill D avidson and J & Poskanzer. 
12 January 1991 
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pnmhistmap 

pnmhistmap— D raw ahistogram for aPGM or PPM file 
SYNOPSIS 

pnmhistmap [-black][-white][-max N][-verbose][pnmfile] 
DESCRIPTION 


pnmhistmap reads a portable anymap as input, although bitmap (PBM ) input produces an error message and no image, and 
produces an image showing a histogram of the color (or gray) values in the input. A graymap (PGM ) input produces a 
bitmap output. A pixmap (PPM ) input produces pixmap output with three overlaid histograms: a red one for the red input, 
a green one for the green input, and a blue onefor the blue input. T he output is fixed in size 256 pixels wide by 200 pixels 
high. 


OPTIONS 
-black Ignores the count of black pixas when scaling the histogram. 
-white Ignores the count of white pixas when scaling the histogram. 


The -black and -white options, which can be used separately or together, are useful for images with alarge percentage of 
pixels whose value is zero or 255, which can cause the renaining histogram data to become unreadably small. N ote that, for 
pixmap inputs, these options apply to all colors; if, for example, the input has a large number of bright-red areas, you will 
probably want to use the -white option. 


-max N Forcethe scaling of the histogram to use N asthe largest-count value. T hisis useful for inputs with a large 
percentage of single-color pixels that are not black or white. 


-verbose Report the progress of making the histogram, including the largest-count value used to scale the output. 


All flags can be abbreviated to their shortest unique prefix. 
BUGS 


Assumes maxval is always 255. Images with a smaller maxva will only use the lower-value side of the histogram. This can be 
overcome either by piping the input through pnmdepth 255 or by cutting and scaling the lower-value side of the histogram. 
N either is a particularly aegant solution. 


Should allow the output size to be specified. 


SEE ALSO 

pgmhist(1), ppmhist(1), pgm(5), ppm(5) 
AUTHOR 

Wilson H. Bent, Jr. (wnb@usc. edu). 

25 Octobe 1993 

pnmindex 

pnmindex— Build a visual index of a bunch of anymaps 
SYNOPSIS 

pnmindex [-size N][-across N][-colors N][-black] pnmfile ... 
DESCRIPTION 


This script makes small versions of a bunch of anymaps, adds labels, and concatenates them together into a collage. 


pnmmargin 


OPTIONS 


-size Controls how big each image becomes, the default is 100x100. 

-across Controls how many images are in each row; the default is six. 

-colors Controls how many colors the final index gets quantized to, if quantization is necessary; the default is 256. 

-black Controls thecolor of the padding between the images; normally it’s white and the labd’s are black lettering on 
white background, but the -b1ack flag reverses this. 


SEE ALSO 


pnmscale(1), pnmcat(1), pomtext(1), ppmquant(1), pnm(5) 


BUGS 
It's very slow. 
It's a csh Script. csh scripts are not portable to System V. Scripts in general are not portable to non-UNIX environments. 


AUTHOR 
Copyright © 1991 by J ef Poskanzer. 


9 January 1991 
pnminvert 
pnminvert— Invert a portable anymap 
SYNOPSIS 
pnminvert [pnmfile] 
DESCRIPTION 
pnminvert reads a portable anymap as input, inverts it black for white, and produces a portable anymap as output. 
SEE ALSO 
pnm(5) 
AUTHOR 
Copyright © 1989 by J ef Poskanzer. 
8 August 1989 
pnmmargin 
pnmmargin— Add a border to a portable anymap 
SYNOPSIS 
pnmmargin [-white;-black;-color colorspec] size [pnmfile] 
DESCRIPTION 


pnmmargin reads a portable anymap as input, adds a border of the specified number of pixels, and produces a portable anymap 
as output. 
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OPTIONS 


You can specify the border color with the -white, -black, and -color flags. If no color is specified, the program makes a 
guess. 


SEE ALSO 
pnm(5) 


BUGS 


It's a script. Scripts are not portable to non-UN IX environments. 


AUTHOR 
Copyright © 1991 by J ef Poskanzer. 


9 January 1991 


pnmnlfilt 


pnmnifilt--N onlinear filters: smooth, alphatrim mean, optimal estimation smoothing, edge enhancenent. 


SYNOPSIS 


pnmnlfilt alpha radius [pnmfile] 


DESCRIPTION 


This is something of a Swiss army knife filter. It has three distinct operating modes. In all of the modes, each pixd in the 
image is examined and processed according to it and its surrounding pixels values. Rather than using the nine pixelsin a 3x3 
block, seven hexagonal area samples are taken, the size of the hexagons being controlled by the radius parameter. A radius 
value of 0.3333 means that the seven hexagons exactly fit into the center pixd (that is, there will be no filtering effect). A 
radius Value of 1.@ means that the seven hexagons exactly fit a 3x3 pixd array. 


ALPHA-TRIMMED MEAN FILTER (0.0 < = alpha < = 0.5) 


The value of the center pixel will be reolaced by the mean of the seven hexagon values, but the seven values are sorted by size 
and the top and bottom alpha portion of the seven are excluded from the mean. This implies that an alpha value of @.0 gives 
the same sort of output as a normal convolution (that is, averaging or smoothing filter), where radius will determine the 
“strength” of the filter. A good value to start from for subtle filtering isalpha = 0.0, radius = 0.55. For amore blatant effect, 
try alpha = 0.0 and radius = 1.0. 


An alpha value of @.5 will cause the median value of the seven hexagons to be used to replace the canter pixel value This sort 
of filter is good for diminating “pop” or single pixel noise from an image without spreading the noise out or smudging 
features on the image. J udicious use of the radius parameter will fine-tune the filtering. Intermediate values of alpha give 
effects somewhere between smoothing and “pop” noise reduction. For subtle filtering, try starting with values of alpha = 0.4, 
radius = 0.6. For amore blatant effect, try alpha = 0.5, radius = 1.0. 


OPTIMAL ESTIMATION SMOOTHING. (1.0 < = alpha < = 2.0) 


This type of filter applies a smoothing filter adaptively over the image. For each pixel, the variance of the surrounding 
hexagon values is calculated, and the amount of smoothing is made inversely proportional to it. T heideais that if the 
variance is small, then it is due to noisein the image while if the variance is large it is because of “wanted” image features. 
As usual, the radius parameter controls the effective radius, but it probably advisable to leave the radius between a.8 and 1.0 
for the variance calculation to be meaningful. The alpha parameter sets the noise threshold, over which less smoothing will 
be done This means that small values of alpha will give the most subtle filtering effect, while large values will tend to smooth 
all parts of theimage. You could start with values like alpha = 1.2, radius = 1.0 and try increasing or decreasing the alpha 
parameter to get the desired effect. T his type of filter is best for filtering out dithering noisein both bitmap and color images. 


pnmnoraw 
EDGE ENHANCEMENT. (-0.1 > = alpha > = -0.9) 


This is the opposite type of filter to the smoothing filter. It enhances edges. The alpha parameter controls the amount of 
edge enhancement, from subtle (-@.1) to blatant (-0.9). The radius parameter controls the effective radius as usual, but 
useful values are between o.5 and 0.9. Try starting with values of alpha = 0.3, radius = 0.8. 

COMBINATION USE 


The various modes of pnmnifilt can be used one after the other to ge@t the desired result. For instance to turn amonochrome 
dithered image into a grayscale image, you could try one or two passes of the smoothing filter, followed by a pass of the 
optimal estimation filter, then some subtle edge enhancement. N ote that using edge enhancement is only liked to be useful 
after one of the nonlinear filters (alpha-trimmed mean or optimal estimation filter), as edge enhancement is the direct 
opposite of smoothing. 


For reducing color quantization noisein images (that is, turning GIF files back into 24-bit files), you could try a pass of the 
optimal estimation filter (alpha 1.2, radius 1.0), a pass of the median filter (alpha 0.5, radius 0.55), and possibly a pass of 
the edge enhancement filter. Several passes of the optimal estimation filter with declining alpha values are more effective than 
a Single pass with a large alpha value. As usual, there is a tradeoff between filtering effectiveness and loosing detail. Experi- 
mentation is encouraged. 


REFERENCES 


Thealpha-trimmed mean filter is based on the description in IEEE CG&A, M ay 1990, page 23, by M ark E. Leeand Richard 
A. Redner, and has been enhanced to allow continuous alpha adjustment. 


The optimal estimation filter is taken from an article “C onverting D ithered Images Back to Grayscale” by Allen Stenger, Dr. 
D obb’sJ ournal, N ovember 1992, and this article references “Digital Image Enhancement and N oise Filtering by U se of Local 
Statistics” by J ong-Sen Lee, |EEE Transactions on Pattern Analydsand M achine Intelligence, M arch 1980. 


The edge nhancement details are from pgmenhance(1), which is taken from Philip R. Thompson’sxim program, which in 
turn took it from Section 6 of “D igital H alftones by D ot Diffusion” by D. E. Knuth, ACM Transaction on Graphics Vol. 6, 
No. 4, October 1987, which in turn got it from two 1976 papers by J. F. Jarviset al. 


SEE ALSO 


pgmenhance(1), pnmconvol(1), pnm(5) 


BUGS 


Integers and tables may overflow if Ppm_MAXMAXVAL is greater than 255. 
AUTHOR 
Graeme W. Gill (graeme@labtam.oz.au). 
5 February 1993 


pnmnoraw 


pnmnoraw— Force a portable anymap into plain format 


SYNOPSIS 


pnmnoraw [pnmfile] 


DESCRIPTION 


pnmnoraw reads a portable anymap as input and writes it out in plain (nonraw) format. T hisis fairly useless if you haven't 
defined the paMPLus_RAWBITS Compile-time option. 
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SEE ALSO 
pnm(5) 


AUTHOR 
Copyright © 1991 by J ef Poskanzer. 
8 January 1991 


pnmpad 
pnmpad— Add borders to portable anymap 


SYNOPSIS 


pnmpad [-white}-black] [-l#] [-r#] [-t#] [-b#] [pnmfile] 


DESCRIPTION 
pnmpad reads a portable anymap as input and outputs a portable anymap with extra borders of the sizes specified. T he color of 
the borders can be set to black Or white (default black). 


SEE ALSO 


pbmmake(1), pnmpaste(1), pbm(5) 


AUTHOR 
Copyright © 1990 by Angus Duggan. Copyright © 1989 by J ef Poskanzer. 


pnmpaste 

pnmpaste— Paste a rectangle into a portable anymap 
SYNOPSIS 

pnmpaste [-replace;-or;-and |-xor] frompnmfile x y [intopnmfile] 
DESCRIPTION 


pnmpaste reads two portable anymaps as input, inserts the first anymap into the second at the specified location, and produces 
a portable anymap the same size as the second as output. If the second anymap is not specified, it is read from stdin. Thex 
andy can be negative in which case they are interpreted relative to the right and bottom of the anymap, respectively. 


This tool is most useful in combination with pnmcut. For instance, if you want to edit a small segment of a large image, and 
your image editor cannot edit the large image, you can cut out the segment you are interested in, edit it, and then paste it 
back in. 


Another useful companion tool is pommask. 


The optional flag specifies the operation to use when doing the paste T he default is -replace. The other logical operations 
are only allowed if both input images are bitmaps. T hese operations act as if white is true and black is FALSE. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


pnmcut(1), pnminvert(1), pnmarith(1), pnm(5), ppmmask(1) 


pnmscale 


21 February 1991 


AUTHOR 
Copyright © 1989, 1991 by J e& Poskanzer. 


pnmrotate 

pnmrotate— Rotate a portable anymap by some angle 
SYNOPSIS 

pnmrotate [-noantialias] angle [pnmfile] 
DESCRIPTION 


pnmrotate reads a portable anymap as input, rotates it by the specified angle, and produces a portable anymap as output. If 
the input fileis in color, the output will be, too; otherwise, it will be grayscale. T he angle is in degrees (floating-point), 
measured counter-clockwise. It can be negative, but it should be between -90 and 90. Also, for rotations greater than 45 
degrees you may get better results if you first use pnmflip to do a 90-degree rotation and then pnmrotate less than 45 degrees 
back the other direction. 


The rotation algorithm is Alan Paeth’s three-shear method. Each shear is implemented by looping over the source pixds and 
distributing fractions to each of the destination pixels. This hasan antialiasing effect— it avoids jagged edges and similar 
artifacts. H owever, it also means that the original colors or gray levels in the image are modified. If you need to keep 
precisely the same set of colors, you can use the -noantialias flag. T his does the shearing by moving pixels without changing 
their values. If you want antialiasing and don’t care about the precise colors, but still need alimited «number* of colors, you 
can run the result through ppmquant. 


All flags can be abbreviated to their shortest unique prefix. 


REFERENCES 

“A Fast Algorithm for General Raster Rotation” by Alan Paeth, Graphics | nterface '86, pages 77-81. 
SEE ALSO 

pnmshear(1), pnmflip(1), pnm(5), ppmquant(1) 
AUTHOR 

Copyright © 1989, 1991 by J & Poskanzer. 

12 January 1991 

pnmscale 

pnmscale— Scale a portable anymap 
SYNOPSIS 


pnmscale s [pnmfile] 

pnmscale -xsize;-width;-ysize,; -height s [pnmfile] 

pnmscale -xscale|-yscale s [pnmfile] 

pnmscale -xscale;-xsize;-width s -yscale;-ysize;-height s [pnmfile] 
pnmscale -xysize x y [pnmfile] 

pnmscale -pixels n [pnmfile] 
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DESCRIPTION 


pnmscale reads a portable anymap as input, scalesit by the specified factor or factors, and produces a portable anymap as 
output. If the input file isin color, the output will be too; otherwise, it will be grayscale. You can both enlarge (scale factor > 
1) and reduce (scale factor <1). 


You can specify one dimension as a pixd size, and the other dimension will be scaled correspondingly. 

You can specify one dimension asa scale and the othe: dimension will not be scaled. 

You can specify different sizes or scales for each axis. 

You can usethe special -xysize flag, which fits the image into the specified size without changing the aspect ratio. 

Or, you can use the -pixels flag, which fits the image into the specified number of pixels without changing the aspect ratio. 
All flags can be abbreviated to their shortest unique prefix. 


If you enlarge by a factor of three or more you should probably add a pnmsmooth step; otherwise, you can see the original 
pixds in the resulting image. 


SEE ALSO 


pbmreduce(1), pnmenlarge(1), pnmsmooth(1), pnm(5) 


AUTHOR 


Copyright © 1989, 1991 by J e& Poskanzer. 
12 January 1991 


pnmshear 


pnmshear— Shear a portable anymap by some angle 


SYNOPSIS 


pnmshear [-noantialias] angle [pnmfile] 


DESCRIPTION 


pnmshear reads a portable anymap as input, shears it by the specified angle, and produces a portable anymap as output. If the 
input fileis in color, the output will be too; otherwise, it will be grayscale. The angleisin degrees (floating-point), and 
measures this: 


wet te---+ 


--+ |glet----+ 
If the angle is negative, it shears the other way: 


--+ | -ant----+ 
/ 


igi 
OLD |\e/ NEW / 
i// 


The angle should not get too close to 90 or -90, or the resulting anymap will be unreasonably wide 

The shearing is implemented by looping over the source pixdis and distributing fractions to each of the destination pixds. 
This has an antialiasing effect— it avoids jagged edges and similar artifacts. H owever, it also means that the original colors or 
gray levels in the image are modified. If you need to keep precisdy the same set of colors, you can use the -noantialias flag. 


pnmtile 


This does the shearing by moving pixels without changing their values. If you want antialiasing and don’t care about the 
precise colors, but still need a limited *number* of colors, you can run the result through ppmquant. 


All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 

pnmrotate(1), pnmflip(1), pnm(5), ppmquant(1) 
AUTHOR 

Copyright © 1989, 1991 by J e& Poskanzer. 

12 January 1991 

pnmsmooth 

pnmsmooth— Smooth out an image 
SYNOPSIS 

pnmsmooth [pnmfile] 
DESCRIPTION 


pnmsmooth smooths out an image by replacing each pixel with the average of its nine immediate naghbors. It is implemented 
as a simple script using pnmconvol. 


SEE ALSO 


pnmconvol(1), pnm(5) 


BUGS 


It's a script. Scripts are not portable to non-UN IX environments. 


AUTHOR 
Copyright © 1989, 1991 by J & Poskanzer 
13 January 1991 


pnmtile 


pnmtile— Replicate a portable anymap into a specified size 


SYNOPSIS 


pnmtile width height [pnmfile] 


DESCRIPTION 


pnmtile reads a portable anymap as input, replicates it until it is the specified size, and produces a portable anymap as output. 


SEE ALSO 
pnm(5) 


AUTHOR 
Copyright © 1989 by J ef Poskanzer. 
13 May 1989 
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pnmtoddif 


pnmtoddif— Convert a portable anymap to DD IF format 


SYNTAX 
pnmtoddif pnmtoddif [-resolution x y] [pnmfile [ddiffile]] 

OPTIONS 
resolution x y Thehorizontal and vertical resolution of the output image in dots per inch. D efaults to 7sapi. 
pnmfile The filename for the image file in PN M format. If this argument is omitted, input is read from stdin. 
ddiffile The filename for the image file to be created in DDIF format. If this argument is omitted, theddiffile is 

written to standard output. It can only specified if apnmfile is also specified. 

DESCRIPTION 
pnmtoddif takes a portable anymap from standard input and converts it into aD DIF image file on standard output or the 
specified D DIF file. 


PBM format (bitmap) data is written as 1-bit D DIF, PGM format data (grayscale) as 8-bit grayscale D DIF, and PPM format 
data is written as 8,8,8-bit color DD IF. All DD IF image files are written as uncompressed. T he data plane organization is 
interleaved by pixd. 


In addition to the number of pixels in the width and height dimension, DDIF images also carry information about the size 
that the image should have, that is, the physical space that a pixel occupies. PBM PLUS images do not carry this information, 
hence it has to be externally supplied. T he default of 78dpi has the beneficial property of not causing a resize on most D igital 
Equipment Corporation color monitors. 


AUTHOR 


Burkhard N eidecker-Lutz 
Digital Equipment Corporation, CEC Karlsruhe 


neideck@nestvx.enet.dec.com 


pnmtofits 
pnmtofits— Convert a portable anymap into FIT S format 


SYNOPSIS 


pnmtofits [-max f ][-min f ][pnmfile] 


DESCRIPTION 


pnmtofits reads a portable anymap as input and produces a FIT S (Flexible | mage T ransport System) file as output. The 
resolution of the output file is either 8 bits/pixd, or 16 bits/pixel, depending on the value of maxvai in the input file If the 
input fileis a portable bitmap or a portable graymap, the output file consists of a single plane image (naxis = 2). If instead 
the input file is a portable pixmap, the output file will consist of a three plane image (NaxIs = 3, NAXIS3 = 3). A full 
description of the FITS format can be found in Atronomy & Astrophysics Supplement Series 44 (1981), page 363. 


OPTIONS 


Flags -min and -max can be used to set DATAMAX, DATAMIN, BSCALE, and BzeRro in the FITS header, but do not cause the data to 
be rescaled. 


SEE ALSO 


fitstopnm(1), pgm(5) 


pnmtops 397 


AUTHOR 


Copyright © 1989 by Wilson H. Bent (whb@hoh-2.att.com), with modifications by Alberto Accomazzi 
(alberto@cfa.harvard.edu). 


5 December 1992 


pnmtops 


pnmtops— Convert portable anymap to PostScript 


SYNOPSIS 
pnmtops [-scale s][-turn}-noturn][-rle|-runlength][-dpi n][-width n][-height n] 
[-center} -nocenter][pnmfile] 

DESCRIPTION 
pnmtops reads a portable anymap as input and produces encapsulated PostScript as output. 


If the input file isin color (PPM ), acolor PostScript file gets written. Some PostScript interpreters can’t handle color 
PostScript. If you have one of these, you will need to run your image through ppmtopgm first. 


N ote that there is no pstopnm tool; this transformation is one-way, because a pstopnm tool would bea full-fledged PostScript 
interpreter, which is beyond the scope of this package. H owever, see the psidtopgm tool, which can read grayscale non-run- 
length PostScript image data. Also, if you’re willing to install the fairly large GhostScript package, it comes with a pstoppm 
script. 


OPTIONS 


The -scale flag controls the scale of the result. The default scale is 1, which on a 300dpi printer such as the Apple 
LaserW rite makes the output look about the same size as the input would if it was displayed on atypical 72dpi screen. To 
ge onePNM pixd per 300dpi printer pixel, use -scale 0.25. 


The -turn and -noturn flags control whether the image gets turned 90 degrees. N ormally, if an image is wider than it is tall, 
it gets turned automatically to better fit the page. If the -turn flag is specified, it will be turned no matter what its shape and 
if the -noturn flag isspecified, it will not beturned no matter what its shape 


The -rie Or -runlength flag specifies run-length compression. This may save time if the host-to-printer link is slow; but 
normally the printer’s processing time dominates, so -rle makes things slower. 


The -dpi flag lets you specify the dots per inch of your output device. T he default is 300dpi. In theory PostScript is device 
independent and you don’t have to worry about this, but in practice its raster rendering can have unsightly bands if the 
device pixels and the image pixels aren’t in sync. 


The -width and -height flags let you specify the size of the page. T he default is 8.5 inches by 11 inches. 


With the -nocenter flag, the output is not centered on the page; it appears in the upper-left corner. T his is useful for 
programs that can include PostScript files, but can’t cope with pictures that are not positioned in the uppe-left corner. The 
default is -center--the image is centered on the page. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 
pnm(5), psidtopgm(1) 
AUTHOR 
Copyright © 1989, 1991 by] e Poskanzer. M odified N ovenber 1993 by Wolfgang Stuerzlinger (wrzlegup.uni-1inz.ac.at). 
26 Octobe 1991 
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pnmtorast 


pnmtorast— Convert a portable pixmap into a Sun raster file 


SYNOPSIS 


pnmtorast [-standard}-rle][pnmfile] 


DESCRIPTION 
pnmtorast reads a portable pixmap as input and produces a Sun raster file as output. 


Color values in Sun raster files are eight bits wide, so pnmtorast will automatically scale colors to havea maxval of 255. An 
extra pnmdepth step is not necessary. 


OPTIONS 


The -standard flag forces the result to bein AT_STANDARD form; the -rie flag, RT_BYTE_ENCODED, which is smaller but, wall, less 
standard. The default is -rie. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


rasttopnm(1), pnm(5) 
AUTHOR 


Copyright © 1989, 1991 by J e& Poskanzer. 
12 January 1991 


pnmtosgi 
pnmtosgi— Convert a portable anymap to an SGI imagefile 


SYNOPSIS 


pnmtosgi [-verbatim} -rle][-imagename Name ][pnmfile] 


DESCRIPTION 


pnmtosgi reads a portable anymap as input and produces an SGI image file as output. The SGI image will be two-dimen- 
sional (one channel) for PBM and PGM input, and three-dimensional (three channds) for PPM. 


OPTIONS 
-verbatim W rite an uncompressed file 


-rle (default) W rite a compressed (run-length- encoded) file. 


-imagename name Writethestring name into the imagename fidd of theheader. Thename stringis limited to 79 characters. If 
no nameis given, pnmtosgi writes no name into this fidd. 


BUGS 
Probably. 


REFERENCES 


SGI image file format documentation (draft v0.95) by Paul H aeberli (paul@sgi.com). Available via FT P at sgi.com:graphics/ 
SGIIMAGESPEC. 


pnmtotiff 


SEE ALSO 


pnm(5), sgitopnm(1) 


AUTHOR 
Copyright © 1994 by Ingo Wilken (tngo.wilken@informatik.uni-oldenburg.de). 


29 January 1994 


pnmtosir 


pnmtosir— Convert a portable anymap into a Solitaire format 


SYNOPSIS 


pnmtosir [pnmfile] 


DESCRIPTION 
pnmtosir reads a portable anymap as input and produces a Solitaire image recorder format. 
pnmtosir producesan MGI TYPE 17 filefor PBM and PGM files. For ppm, it writes an MGI TYPE 11 file 


SEE ALSO 


sirtopnm(1), pnm(5) 


AUTHOR 
Copyright © 1991 by M arvin Landis. 
20 March 1991 


pnmtotift 


pnmtotiff— Convert a portable anymap into a TIFF file 


SYNOPSIS 


pnmtotiff [-none|-packbits| -lzw|-g3{-g4][-2d][-fill][-predictor n] 
[-msb21sb}-lsb2msb] [-rowsperstrip n][pnmfile] 


DESCRIPTION 


pnmtotiff reads a portable anymap as input. Produces a TIFF file as output. 


OPTIONS 


By default, pnmtotitf creates a TIFF file with LZW compression. Thisis your best bet most of the time. H owever, some 
TIFF readers can’t deal with it. If you want to try another compression schane or tweak some of the other een more 
obscure output options, there are a number of flags to play with. 


The -none, -packbits, -1zw, -g3,and-g4 options are used to override the default and set the compression scheme used in 
creating the output file. TheC CITT Group 3 and Group 4 compression algorithms can only be used with bilevel data. The 
-2d and -fi11 options are meaningful only with Group 3 compression: -2d requests two-dimensional encoding, while -fi11 
requests that each encoded scanline be zero-filled to a byte boundary. The -predictor option is only meaningful with LZ W 
compression: a predictor value of 2 causes each scanline of the output image to undergo horizontal differencing before it is 
encoded; a value of 1 forces each scanline to be encoded without differencing. By default, pnmtotiff creates aTIFF file with 
msb-to-1sb fill order. The -msb21sb and -1sb2msb options are used to override the default and set the fill order used in 
creating thefile. The -rowsperstrip option can be used to set the number of rows (scanlines) in each strip of data in the 
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output file. By default, the output file has the number of rows per strip set to a value that will ensure each strip isno more 
than eight kilobytes long. 


BUGS 


This program is not self-contained. To use it you must fetch the TIFF Software package listed in the oTHER.sysTems file and 
configure pamPLus to use libtift. See PBM -PLUS’sM akefile for details on this configuration. 


SEE ALSO 


tifftopnm(1), pnm(5) 


AUTHOR 


Derived by J ef Poskanzer from ras2tiff.c, which is Copyright© 1990 by Sun M icrosystems, Inc. Author: Patrick J. 
N aughton (naughton@wind.sun.com). 


13 January 1991 
pnmtoxwd 
pnmtoxwd— C onvert a portable anymap into an X11 window dump 
SYNOPSIS 
pnmtoxwd [-pseudodepth n][-directcolor][pnmfile] 
DESCRIPTION 


pnmtoxwd reads a portable anymap as input and produces an X11 window dump as output. This window dump can be 
displayed using the xwud tool. 


Normally, pnmtoxwd produces a StaticG ray dump file for PBM and PGM files. For ppm, it writes a PseudoC olor dump file if 
there are up to 256 colorsin theinput, and a DirectC olor dump file otherwise The -directcolor flag can be used to forcea 
DirectC olor dump. T he -pseudodepth flag can be used to change the depth of PseudoC olor dumps from the default of 8 bits/ 
256 colors. 


SEE ALSO 


xwdtopnm(1), pnm(5), xwud(1) 
AUTHOR 


Copyright© 1989, 1991 by J e& Poskanze. 
24 September 1991 


ppm3d 


ppm3d— C onvert two portable pixmap into ared/blue 3D glasses pixmap 


SYNOPSIS 


ppm3d leftppmfile rightppmfile [horizontal_offset ] 


DESCRIPTION 


ppm3d reads two portable pixmaps as input and produces a portable pixmap as output, with theimages overlapping by 
horizontal_offset pixelsin blue/red format. 


horizontal_offset defaults to 30 pixels. Pixmapsmus be the same size. 


ppmchange 


SEE ALSO 
ppm(5) 
AUTHOR 
Copyright © 1993 by David K. Drum. 
2 N ovanber 1993 


ppmbrighten 
ppmbrighten— Change an image's saturation and value from an HSV map 


SYNOPSIS 


ppmbrighten [-n] [-s <+- saturation>] [-v <+- value>] <ppmfile> 


DESCRIPTION 


ppmbrighten reads a portable pixmap as input, converts the image from RGB space to H SV space, and changes the value by 
<+- value> aS a percentage the same with the saturation. Use 


ppmbrighten -v 100 
to add 100 percent to the value 
Then option normalizes the value to exist between 0 and 1 (normalized). 


SEE ALSO 
pgmnorm(1), ppm(5) 
AUTHOR 
Copyright© 1990 by Brian M offet. Copyright© 1989 by J ef Poskanzer. 


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this 
permission notice appear in supporting documentation. T his software is provided “as is” without express or implied 
warranty. 


NOTES 
This program does not change the number of colors. 
20 N ovenber 1990 


ppmchange 


ppmchange— Changeall pixes of one color to another in a portable pixmap 


SYNOPSIS 


ppmchange oldcolor newcolor [...] [ppmfile] 


DESCRIPTION 


ppmchange reads a portable pixmap asinput and changes all pixds of ol dcolor to newcol or, leaving all others unchanged. Up 
to 256 colors may be replaced by specifying couples of colors on the command line 


Part |: User Commands 


Thecolors can be specified in five ways: 


m Aname, assuming that a pointe to an X11-style color names file was compiled in. 

An X11-style hexadecimal specifier: rgb:r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

An X11-style decimal specifier: rgbi:r/g/b, where r, g, and b are floating-point numbers betwee 0 and 1. 

For backwards compatibility, an old-X 11-style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, OF #rrrrggggbbbb. 
For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (This style was added beforeMIT cameup with thesimilar rgbi style) 


SEE ALSO 


pgmtoppm(1), ppm(5) 


AUTHOR 


Wilson H . Bent, Jr. (wnb@usc.edu), with modifications by Alberto Accomazzi (alberto@cfa. harvard. edu). 


3 December 1993 


ppmdim 

ppmdim— Dim a portable pixmap down to total blackness 
SYNOPSIS 

ppmdim dimfactor [ppmfile] 


DESCRIPTION 


ppmdim reads a portable pixmap as input and diminishes its brightness by the specified dimfactor down to total blackness. T he 
dimfactor may bein the range from 0.0 (total blackness, deep night, nada, null, nothing) to 1.0 (original picture's bright- 
ness). 


AS pnmgamma does not do the brightness correction in the way | wanted it, | wrote this small program. 
ppmdim is Similar to ppmbrighten, but not exactly the same. 


SEE ALSO 


ppm(5), ppmflash(1), pnmgamma(1), ppmbrighten(1) 


AUTHOR 
Copyright© 1993 by Frank N eumann. 


16 N ovenber 1993 


ppmdist 


ppmdist— Simplistic grayscale assignment for machine-generated color images 


SYNOPSIS 
ppmdist [-intensity|-frequency][ppmfile] 
DESCRIPTION 


ppmdist reads a portable pixmap asinput and performs a simplistic grayscale assignment intended for use with grayscale or 
bitmap printers. 


ppmdither 


Often conversion from ppm to pgm will yield an image with contrast too low for good printer output. The program maximizes 
contrast between the gray levels’ output. 


A ppm input of n colors is read, and apgm of n gray levels is written. The gray levels take on the values @.. .n-1, while maxval 
takes on n-1. 

The mapping from color to stepped grayscale can be performed in order of input pixd intensity, or input pixel frequency 
(number of repetitions). 


OPTIONS 
-frequency Sort input colors by thenumber of times a color appears in theinput, before mapping to evenly distrib- 
uted gray levels of output. 
-intensity Sort input colors by thar grayscale intensity, before mapping to evenly distributed gray levels of output. 
This is the default. 
BUGS 
H elpful only for images with a very small number of colors. Perhaps should have been an option to ppmtopgm(1). 
SEE ALSO 
ppmtopgm(1), ppmhist(1), ppm(5) 
AUTHOR 


Copyright© 1993 by Dan Stromberg. 
22 July 1992 


ppmdither 
ppmdither— Ordered dither for color images 


SYNOPSIS 


ppmdither [-dim di mension][-red shades ][-green shades ][-blue shades ][ppmfile] 


DESCRIPTION 


ppmdither reads a portable pixmap as input, and applies dithering to it to reduce the number of colors used down to the 
specified number of shades for each primary. T he default number of shades isred=5, green=9, blue=5, for atotal of 225 
colors. To convert the image to a binary RGB format suitable for color printers, use -red 2 -green 2 -blue 2. Themaximum 
number of colors that can be used is 256 and can be computed as the product of the number of red, green, and blue shades. 


OPTIONS 
-dim dimension Thesizeof the dithering matrix. M ust bea power of 2. 
-red shades Thenumber of red shades to be used; minimum of 2. 


-green shades | Thenumber of green shades to be used; minimum of 2. 
-blue shades Thenumber of blue shades to be used; minimum of 2. 


SEE ALSO 
pnmdepth(1), ppmquant(1), ppm(5) 
AUTHOR 
Copyright© 1991 by Christos Zoulas. 
14 July 1991 
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ppmf lash 


ppmflash— Brighten a picture up to complete white out 


SYNOPSIS 


ppmflash flashfactor [ppmfile] 


DESCRIPTION 


ppmflash reads a portable pixmap as input and increases its brightness by the specified f! ashfactor up to atotal white out 
image Theflashfactor may bein the range from 0.0 (original picture's brightness) to 1.0 (full white out, T he Second 
After). 


AS pnmgamma does not do the brightness correction in the way | wanted it, | wrote this small program. 
This program is similar to ppmbrighten, but not exactly the same 


SEE ALSO 


ppm(5), pomdim(1), pnmgamma(1), ppmbrighten(1) 


AUTHOR 
Copyright© 1993 by Frank N eumann. 


16 N ovenber 1993 


ppmforge 


ppmforge— Fractal forgeries of clouds, planets, and starry skies 


SYNOPSIS 
ppmforge [-clouds][-night][-dimension dimen][-hour hour ][-inclination|-tilt angle] 
[-mesh size][-power factor ][-glaciers | evel ][-ice level ][-saturation sat ] 
[-seed seed] [-stars fraction][-xsize;-width width][-ysize;-height hei ght ] 
DESCRIPTION 


ppmforge generates three kinds of “random fractal forgeries,” the term coined by Richard F. Vossof the IBM Thomas 

J. Watson Research C enter for seemingly realistic pictures of natural objects generated by simple algorithms enbodying 
randomness and fractal saf-similarity. The techniques used by ppmforge are essentially those given by Voss, particularly the 
technique of spectral synthesis explained in more detail by D ietmar Saupe. (The “See Also” subsection provides more 
detailed information about these men’s work.) 


The program generates two varieties of pictures, planets and clouds, which are just different renderings of data generated in 
an identical manner, illustrating the unity of the fractal structure of these very different objects. A third type of picture, a 
starry sky, is synthesized directly from pseudorandom numbers. 


The generation of planets or clouds begins with the preparation of an array of random data in the frequency domain. The 
size of this array, the mesh 9ze can be set with the -mesh option; the larger the mesh, the more realistic the pictures, but the 
calculation time and memory requirement increases as the square of the mesh size. The fractal dimension, which you can 
specify with the -dimension option, determines the roughness of the terrain on the planet or the scale of detail in the clouds. 
Asthe fractal dimension is increased, more high frequency components are added into therandom mesh. 


After the mesh is generated, an inverse two-dimensional Fourier transform is peformed upon it. This converts the original 
random frequency domain data into spatial amplitudes. You scale the real components that result from the Fourier transform 
into numbers from 0 to 1 associated with each point on the mesh. You can further modify this number by applying a power 
law scale to it with the -power option. Unity scaleleaves the numbers unmodified; a power scale of 0.5 takes the square root 
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of the numbers in the mesh, while a power scale of 3 replaces the numbers in the mesh with ther cubes. Power law scaling is 
best envisioned by thinking of the data as representing the devation of terrain; powers less than one yidd landscapes with 
vertical scarps that look like glacial-carved valleys; powers greater than one make fairy-castle spires (which require large mesh 
sizes and high resolution for best results). 


After these calculations, you have an array of the specified size containing numbers that range from 0 to 1. The pixmaps are 
generated as follows: 


Clouds A color map iscreated that ranges from pure blue to white by increasing admixture (desaturation) of blue with 
white N umbersless than 0.5 are colored blue, and numbers between 0.5 and 1.0 are colored with corresponding 
levels of white, with 1.0 being pure white 

Planet | Themesh is projected onto asphere Values less than 0.5 are treated as water and values between 0.5 and 1.0 as 
land. The water areas are colored based on the water depth; land, based on its elevation. The random depth data 
are used to create clouds over the oceans. An atmosphere approximately like the Earth’s is simulated; its light 
absorption is calculated to create a blue cast around the limb of the plane. A function that rises from 0 to 1 based 
on latitude is modulated by the local devation to generate polar ice caps— high altitude terrain carries glaciers 
farther from the pole. Based on the position of the star with respect to the observer, the apparent color of each 
pixd of the planet is calculated by ray-tracing from the star to the planet to the observer and applying a lighting 
modd that sums ambient light and diffuse reflection (for most planets ambient light is zero, as their primary star 
is the only source of illumination). Additional random data are used to generate stars around the planed. 


Night A sequence of pseudorandom numbers is used to generate stars with a user-specified density. 


Cloud pictures always contain 256 or fewer colors and may be displayed on most color-mapped devices without further 
processing. Planet pictures often contain tens of thousands of colors that must be compressed with ppmquant OF ppmdither 
before encoding in a color-mapped format. If the display resolution is high enough, ppmdither generally produces better- 
looking planets. ppmquant tends to create discrete color bands, particularly in the oceans, which are unrealistic and distract- 
ing. Thenumbe of colors in starry sky pictures generated with the -night option depends on the value specified for 
-saturation. Small values limit the color temperature distribution of thestars and reduce the number of colors in the image. 
If the -saturation is set to e, none of thestars will be colored and the resulting image will never contain more than 256 
colors. Night sky pictures with many different star colors often look best when color-compressed by pnmdepth rather than 
ppmquant OF ppmdither.T ry newmaxval settings of 63, 31, or 15 with pnmdepth to reduce the number of colors in the picture to 
256 or fewer. 


OPTIONS 
-clouds Generate clouds. A pixmap of fractal clouds is generated. Sdecting clouds sets the default 
for fractal dimension to 2.15 and power scale factor to 0.75. 
-dimension di men Sets the fractal dimension to the specified dimen, which may be any floating-point value 


between 0 and 3. Higher fractal dimensions create more “chaotic” images, which require 
higher resolution output and alarger FFT mesh size to look good. If no dimension is 
specified, 2.4 isused when generating planets and 2.15 for clouds. 


-glaciers | evel The floating-point | eve! setting controls the extent to which terrain devation causes ice to 
appear at lower latitudes. T he default value of 0.75 makes the polar caps extend toward the 
equator across high terrain and forms glaciers in the highest mountains, as on Earth. H igher 
values make ice sheets that cover more and more of the land surface, simulating planets in 
the midst of an ice age. Lower values tend to be boring, resulting in unrealistic geometrically 
precise ice cap boundaries. 

-hour hour W hen generating a planet, hour isused as the hour angle at the central meridian. If you 
specify -hour 12, for example, the planet will be fully illuminated, corresponding to high 
noon at the longitude at the center of the screen. You can specify any floating-point value 
between 0 and 24 for hour, but values which place most of the planet in darkness (0 to 4 
and 20 to 24) result in crescents which, while pretty, don’t give you many illuminated pixas 
for the amount of computing that’s required. If no -hour option is specified, a random hour 
angle is chosen, biased so that only 25 percent of the images generated will be crescents. 
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-ice | evel 


-inclination|-tilt angle 


-mesh size 


-night 


-power factor 


-saturation sat 


Sets the extent of the polar ice caps to the given floating-point 1eve1. T he default level of 
0.4 producesice caps similar to those of the Earth. Smaller values reduce the amount of ice 
while larger -ice settings create more prominent ice caps. Sufficiently large values, such as 
100 or more, in conjunction with small settings for -glaciers (try 0.1) create “ice balls” like 
Europa. 

The inclination angle of the planet with regard to its primary star is set to angle, which can 
be any floating-point value from -90 to 90. T he inclination angle can be thought of as 
specifying, in degrees, the “season” the planet is presently experiencing or, more precisely, 
the latitude at which the star transits the zenith at local noon. If 0, the planet is at equinox; 
the star is directly overhead at the equator. Positive values represent summer in the northern 
hemisphere, negative values summer in the southern hemisphere. T he Earth’s inclination 
angle, for example, is about 23.5 at the} une solstice, 0 at the equinoxesin M arch and 
September, and -23.5 at the D ecember solstice. If no inclination angle is specified, a 
random value between -21.6 and 21.6 degrees is chosen. 


A mesh of size bysize will be used for the fast Fourier transform (FFT ). N ote that 
memory requirements and computation speed increase as the square of size; if you double 
the mesh size, the program will use four times the memory and run four times aslong. T he 
default mesh is 256x256, which produces reasonably good looking pictures while using half a 
megabyte for the 256x256 array of single precision complex numbers required by the FFT. 
On machines with limited memory capacity, you may have to reduce the mesh size to avoid 
running out of RAM . Increasing the mesh size produces better looking pictures; the 
difference becomes particularly noticeable when generating high-resolution images with 
relatively high fractal dimensions (between 2.2 and 3). 


A starry sky is generated. T he stars are created by the same algorithm used for the stars that 
surround plane pictures, but the output consists exclusively of stars. 


Sets the power factor used to scale elevations synthesized from the FFT to factor, which can 
be any floating-point number greater than zero. If no factor is specified, a default of 1.2 is 
used if a planet is being generated, or 0.75 if clouds are sdected by the -clouds option. T he 
result of the FFT image synthesis is an array of elevation values between 0 and 1.A 
nonunity power factor exponentiates each of these elevations to the specified power. For 
example, a power factor of 2 squares each value, while a power factor of 0.5 replaces each 
with its square root. (N ote that exponentiating values between 0 and 1 yidds values that 
remain within that range.) Power factors less than 1 emphasize large-scale elevation changes 
at the expense of small variations. Power factors greater than 1 increase the roughness of the 
terrain and, like high fractal dimensions, may require a larger FFT mesh size or higher 
screen resolution to look good. 

Controls the degree of color saturation of the stars that surround plane pictures and fill 
starry skies created with the -night option. The default value of 125 creates stars that 
resemble the sky as seen by the human eye from Earth’s surface Stars are dim; only the 
brightest activate the cones in the human retina, causing color to be perceived. H igher 
values of sat approximate the appearance of stars from Earth orbit, where better dark 
adaptation, absence of sky glow, and the concentration of light from a given star onto a 
smaller area of the retina thanks to the lack of atmospheric turbulence enhances the 
perception of color. Values greater than 250 create “science fiction” skies that, while pretty, 
don’t occur in this universe 

Thanks to the inverse square law combined with nature's love of mediocrity, there are 
many, many dim stars for every bright one. This population relationship is accuratdy 
reflected in the skies created by ppmforge. Dim, low massstars live much longer than bright, 
massive stars; consequently there are many reddish stars for every blue giant. T his relation- 
ship is preserved by ppmforge. You can reverse the proportion, simulating the sky as seen in a 
starburst galaxy, by specifying a negative sat value. 
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-seed num Sets the seed for the random number generator to the integer num. T he seed used to create 
each picture is displayed on standard output (unless suppressed with the -quiet option). 
Pictures generated with the same seed will be identical. If no -seea is specified, arandom 
seed derived from the date and time will be chosen. Specifying an explicit seed allows you to 
re-render a picture you particularly like at a higher resolution or with different viewing 


parameters. 

-stars fraction Specifies the percentage of pixels, in tenths of a percent, that will appear as stars, either 
surrounding a planet or filling the entire frame if -night is specified. The default fraction is 
100. 

-xsize!-width width Sets the width of the generated image to wi dth pixels. The default width is 256 pixds. 


Images must be at least as wide as they are high; if a width less than the height is specified, it 
will be increased to equal the height. If you must havea long, skinny pixmap, make a square 
onewith ppmforge, then use pnmcut to extract a portion of the shape and size you require. 

-ysize!-height height Sets the height of the generated image to height pixels. The default height is 256 pixels. If 
the haght specified exceeds the width, the width will be increased to equal the hdght. 


All flags can be abbreviated to their shortest unique prefix. 
BUGS 


The algorithms require the output pixmap to be at least as wide as it is high, and the width to be an even number of pixds. 
T hese constraints are enforced by increasing the size of the requested pixmap if necessary. 


You may haveto reduce the FFT mesh size on machines with 16-bit integers and segmented pointer architectures. 


SEE ALSO 
pnmcut(1), pnmdepth(1), ppmdither(1), ppmquant(1), ppm(5) 


“Random Fractal Forgeries’ by Richard F. Voss, in Fundamental Algorithms for Computer Graphics by Earnshaw et al. Berlin: 
Springer-V erlag, 1985. 


The Science Of Fractal | mages, edited by H. O. Patgen and D. Saupe. N ew York: Springer-Verlag, 1988. 


AUTHOR 


John Walker 

Autodesk SA 

Avenue des C hamps-M ontants 14b 
CH-2074 MARIN 

Suisse/ Schweiz/Svizzera/Svizra/ Switzerland 


Usenet: kelvin@Autodesk.com 
Fax: 038/33 88 15 
Voice 038/33 76 33 


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T his software is provided “as is” without express or implied warranty. 


PLUGWARE! If you like this kind of stuff, you may also enjoy J ames Gleick’s “Chaos— T he Software” for MS-DOS, 
available for $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 M arinship 
W ay, Sausalito, CA 94965, USA. T dephone: 800-688-2344 toll-free or, outside the U.S. 415-332-2344 Ext 4886. 

Fax: 415-289-4718. “C haos— T he Software” includes a more comprehensive fractal forgery generator that creates three- 
dimensional landscapes as wd as clouds and planets, plus five more modules that explore other aspects of Chaos. T he user 
guide of more than 200 pages includes an introduction by J ames Glaick and detailed explanations by Rudy Rucker of the 
mathematics and algorithms used by each program. 


25 Octobe 1991 
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ppmhist 


ppmhist— Print a histogram of a portable pixmap 


SYNOPSIS 


ppmhist [ppmfile] 


DESCRIPTION 


ppmhist reads a portable pixmap as input and generates a histogram of the colors in the pixmap. 


SEE ALSO 


ppm(5), pgmhist(1) 
AUTHOR 
Copyright® 1989 by J ef Poskanzer. 
3 April 1989 


ppmmake 


ppmmake— C reate a pixmap of a specified size and color 


SYNOPSIS 


ppmmake color width height 


DESCRIPTION 
ppmmake produces a portable pixmap of the specified color, width, and height. 
The color can be specified in five ways: 


m Aname, assuming that a pointer to an X11-style color names file was compiled in. 

An X11-style hexadecimal specifier: rgb:r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

An X11-style decimal specifier: rgbi:r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

For backwards compatibility, an old-X 11-style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, OF #rrrrggggbbbb. 
For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (This style was added beforeMIT cameup with thesimilar rgbi style) 


SEE ALSO 


ppm(5), pbmmake(1) 


AUTHOR 
Copyright© 1991 by J ef Poskanzer. 


24 September 1991 


ppmmix 


ppmmix— Blend together two portable pixmaps 


SYNOPSIS 


ppmmix fadefactor ppmfilel ppmfile2 


ppmntsc 
DESCRIPTION 


ppmmix reads two portable pixmaps as input and mixes them together using the specified fade factor. T he fade factor may be 
in the range from 0.0 (only ppmfi | e1’s image data) to 1.0 (only ppmf i! e2’s image data). Anything in between gains a smooth 
blend between the two images. 


The two pixmaps must have the same size 
SEE ALSO 
ppm(5) 
AUTHOR 
Copyright© 1993 by Frank N eumann. 
16 N ovenber 1993 


ppmnorm— N ormalize the contrast in a portable pixmap 
SYNOPSIS 

ppmnorm[-bpercent N | -bvalue N][-wpercent N | -wvalue N][ppmfile] 
DESCRIPTION 


ppmnorm reads a portable pixmap asinput; normalizes the contrast by forcing the lightest pixds to white the darkest pixels to 
black, and linearly rescaling the ones in between; and produces a portable pixmap as output. 


It works by computing the rdative gray levd of each pixel as with ppmtopgm, and uses those values to scale the RGB levels. 
N ote that this is different from using pgmnorm on the individual red, green, and blue graymaps (as produced by ppmtorgb3) 
and recombining them. 


OPTIONS 


By default, the darkest two percent of all pixds are mapped to black, and the lightest one percent are mapped to white You 
can override these percentages by using the -bpercent and -wpercent flags, or you can specify the exact pixel values to be 
mapped by using the -bvalue and -wvalue flags. Appropriate numbers for the flags can be gotten from the ppmhist tool. If 
you just want to enhance the contrast, then choose values at abows in the histogram; for example, if value 29 represents 3 
percent of the image but value 30 represents 20 percent, choose 30 for bvalue. If you want to lighten the image, then set 
bvalue to o and just fiddle with wvalue; similarly, to darken the image, set walue to maxval and play with bvalue. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


pgmnorm(1), ppmhist(1), ppm(5) 
AUTHOR 
Wilson H . Bent, Jr. (whb@usc.edu), heavily based on the pgmnorm filter by J ef Poskanzer. 
7 October 1993 


ppmntsc 


ppmntsc— M akea portable pixmap look like it is taken from an American TV show 


SYNOPSIS 


ppmntsc dimfactor [ppmfile] 
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DESCRIPTION 


ppmntsc reads a portable pixmap asinput and dims every other row of image data down by the specified dim factor. This 
factor may be in the range of 0.0 (the alternate lines are totally black) to 1.0 (original image). 


This creates an effect similar to what | saw once in the video clip “You Could be M ine” by Guns'n’ Roses. In the scene l’m 
talking about you can see) ohn Connor on his motorbike, looking up from the water trench (?) he’s standing in. While the 
camera pulls back, the image becomes “normal” by brightening up the alternate rows of it. | thought this would be an 
interesting effect to tryin M PEG. | did not yet check this out, however. T ry for yourself. 


SEE ALSO 
ppm(5), ppmdim(1) 
AUTHOR 
Copyright© 1993 by Frank N eumann. 
16 N ovenber 1993 


ppmpat 


ppmpat— M akea pretty pixmap 


SYNOPSIS 


ppmpat -gingham2{-g2;-gingham3; -g3|-madras;-tartan, -poles; -squig;-camo, 
-anticamo width height 


DESCRIPTION 
ppmpat produces a portable pixmap of the specified width and height, with a pattern in it. 


This program is mainly to demonstrate use of the ppmdraw routines, asimple but powerful drawing library. See the ppmdraw.h 
include file for more information on using these routines. Still, some of the patterns can be rather pretty. If you have a color 
workstation, something like ppmpat -squig 300 300 | "ppmquant 128" should generate a nice background. 


OPTIONS 
The different flags specify various different pattern types: 


-gingham2 A gingham check pattern. Can be tiled. 

-gingham3 A slightly more complicated gingham. Can betiled. 

-madras A madras plaid. Can betiled. 

-tartan A tartan plaid. Can be tiled. 

-poles Color gradients centered on randomly placed poles. M ay need to be run through ppmquant. 

-squig Squiggly tubular pattern. C an be tiled. M ay need to berun through ppmquant. 

-camo Camouflage pattern. M ay need to be run through ppmquant. 

-anticamo Anticamouflage pattern; like -camo, but ultra-bright colors. M ay need to berun through ppmquant. 


All flags can be abbreviated to their shortest unique prefix. 
REFERENCES 


Some of the patterns are from “D esigner’s Guide to Color 3” by J eanne Allen. 


SEE ALSO 


pnmtile(1), ppmquant(1), ppm(5) 


ppmquant 


4 Sentenber 1989 


AUTHOR 
Copyright© 1989 by J ef Poskanzer. 


ppmquant 


ppmquant— Q uantize the colorsin a portable pixmap down to a specified number 


SYNOPSIS 


ppmquant [-floyd|-fs] ncolors [ppmfile] 
ppmquant [-floyd|-fs] -map mapfile [ppmfile] 


DESCRIPTION 


ppmquant reads a portable pixmap as input. It chooses ncolors colors to best represent the image, maps the existing colors to 
the new ones, and writes a portable pixmap as output. 


The quantization method is H eckbett’s “median cut.” 


Alternately, you can skip the color-choosing step by specifying your own set of colors with the -map flag. Themapfile is just 
a ppm file it can be any shape, all that matters is the colorsin it. For instance, to quantize down to the 8-color IBM TTL 
color set, you might use the following: 

P3 

81 

255 

000 

255 0 0 

0 255 0 

0 @ 255 

255 255 0 

255 @ 255 

@ 255 255 

255 255 255 


If you want to quantize one pixmap to use the colors in another one, just use the second one as the mapfile You don’t have 
to reduce it down to only one pixel of each color, just use it asis. 


The -floyd/-fs flag enables a Floyd-Steinberg error diffusion step. Floyd-Steinberg gives vastly better results on images 
where the unmodified quantization has banding or other artifacts, especially when going to asmall number of colors such as 
the preceding IBM set. H owever, it does take substantially more CPU time, so the default is off. 


All flags can be abbreviated to their shortest unique prefix. 
REFERENCES 


“Color | mage Q uantization for Frame Buffer Display,” by Paul H eckbert, stacRaPH '82 Proceedings, page 297. 


SEE ALSO 


ppmquantall(1), pnmdepth(1), ppmdither(1), ppm(5) 
AUTHOR 


Copyright© 1989, 1991 by J & Poskanze. 
12 January 1991 
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ppmquantall 


ppmquantall1— RUN ppmquant on abunch of files all at once, so they share a common colormap 


SYNOPSIS 


ppmquantall ncolors ppmfile ... 


DESCRIPTION 


ppmquantall takes a bunch of portable pixmap as input. It choosesncol ors colors to best represent all of the images, maps the 
existing colors to the new ones, and overwrites the input files with the new quantized versions. 


Verbose explanation: Say you have a dozen pixmaps that you want to display on the screm all at thesame time. Your screen 
can only display 256 different colors, but the pixmaps have a total of a thousand or so different colors. For a single pixmap, 
you solve this problan with ppmquant; this script solves it for multiple pixmaps. All it does is concatenate them together into 
one big pixmap, run ppmquant on that, and then split it up into little pixmaps again. 


(N ote that another way to solve this problem is to preselect a set of colors and then use ppmquant’s -map option to separatdy 
quantize each pixmap to that set.) 


SEE ALSO 
ppmquant(1), ppm(5) 
BUGS 


It's a csh script. csh scripts are not portable to System V. Scriptsin general are not portable to non-UNIX environments. 


AUTHOR 
Copyright© 1991 by J ef Poskanzer. 
27 July 1990 


ppmavga 


ppmqvga— 8-plane quantization 


SYNOPSIS 
ppmqvga [ options ] [ input file ] 
DESCRIPTION 


ppmqvga quantizes PPM files to aght planes, with optional Floyd-Steinberg dithering. Input isa PPM file from the file 
named, or standard input if no file is provided. 


OPTIONS 
-d dither Apply Floyd-Steinberg dithering to the data 
-q quiet Produces no progress reporting, and no terminal output unless an error occurs. 
-v verbose Produces additional output describing the number of colors found, and some information on the resulting 
mapping. M ay be repeated to generate loads of internal table output, but generally only useful once 
EXAMPLES 


ppmqvga -d my_image.ppm | ppmtogif >my_image.gif 


tgatoppm zombie.tga | ppmqvga | ppmtotif > zombie.tif 


ppmshift 


SEE ALSO 


ppmquant 


DIAGNOSTICS 


Error messages if problens; various leves of optional progress reporting. 


AUTHORS 


Original by LyleRains (1rains@netcom.com) aS ppmq256 and ppmq256fs combined; documented and enhanced by Bill D avidsen 
(davidsen@crd.ge.com). 


COPYRIGHT 


Copyright© 1991, 1992 by Bill D avidsen, all rights reserved. The program and documentation may be freely distributed by 
anyone in source or binary format. Please clearly note any changes. 


Local 


ppmreliet 


ppmrelief— Run aLaplacian rdief filte’ on a portable pixmap 


SYNOPSIS 


ppmrelief [ppmfile] 
DESCRIPTION 

ppmrelief reads a portable pixmap as input, does a Laplacian relief filter, and writes a portable pixmap as output. 

The Laplacian rdief filter is described in Beyond Photography by H olzmann, equation 3.19. It’s a sort of edge-detection. 
SEE ALSO 


pgmbentley(1), pgmoil(1), ppm(5) 
AUTHOR 


Copyright© 1990 by Wilson Bent (whb@hoh-2.att.com). 
11 January 1991 


ppmshift 
ppmshift— Shift lines of a portable pixmap left or right by a random amount 


SYNOPSIS 


ppmshift shift [ppmfile] 


DESCRIPTION 
ppmshift reads a portable pixmap as input and shifts every row of image data to the left or right by acertain amount. The 
shift parameter determines by how many pixels a row is to be shifted at most. 


Another one of those effects | intended to use for M PEG tests. Unfortunately, this program will not hdp me here— it creates 
patterns that are too random to be used for animations. Still, it might give interesting results on still images. 
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EXAMPLE 


Check this out: Save your favorite moda’s picture from something like alt binaries. pictures. supermodels (Okay, or from 
any other picture source), convert it to ppm, and process it like this, assuming the picture is 800x600 pixds: 


1. Take the upper half and leaveit like it is: pnmcut @ @ 800 300 cs.ppm >upper.ppm. 

2. Takethe lower half, flip it upside down, dim it, and distort it alittle pnmcut © 300 800 300 cs.ppm ! pnmflip -tb ! 
ppmdim @.7 | ppmshift 10 >lower.ppm. 

3. Concatenate the two pieces: pnmcat -tb upper.ppm lower.ppm >newpic.ppm. 


Theresulting picture looks like the image being reflected on a water surface with slight ripples. 


SEE ALSO 
ppm(5), pnmcut(1), pnmf1ip(1), ppmdim(1), pnmcat(1) 
AUTHOR 
Copyright© 1993 by Frank N eumann. 
16 N ovember 1993 


ppmspread 


ppmspread— D isplace a portable pixmap’s pixals by arandom amount 


SYNOPSIS 
ppmspread amount [ppmfile] 
DESCRIPTION 


ppmspread reads a portable pixmap as input and moves every pixel around a bit relative to its original position. amount 
determines by how many pixels a pixd isto be moved around at most. 


Pictures processed with this filter will seem to be somewhat dissolved or unfocussed (although they appear more coarse than 
images processed by something like pnmconvol). 


SEE ALSO 
ppm(5), pnmconvo1(1) 
AUTHOR 
Copyright© 1993 by Frank N eumann. 
16 N ovanber 1993 


ppmtoacad 


ppmtoacad— Convert portable pixmap to AutoCAD database or slide 


SYNOPSIS 
ppmtoacad [-dxb][-poly][-background colour ][-white][-aspect ratio][-8][ppmfile] 
DESCRIPTION 


ppmtoacad reads a portable pixmap as input. Produces an AutoCAD slidefile or binary database import (D XB) file as output. 
If NO ppmfile is specified, input is read from standard input. 


OPTIONS 


-dxb 


-poly 


-background color 


-white 


-aspect ratio 


“8 


ppmtoacad 


An AutoCAD binary database import (D XB) file is written. T his file is read with the pxBINn 
command and, once loaded, becomes part of the AutoCAD geometrical database and can be 


viewed and edited 
in the database; thi 


ike any other object. Each sequence of identical pixels becomes a separate object 
scan result in very large AutoCAD drawing files. H owever, if you want to trace 


over a bitmap, it lets you zoom and pan around the bitmap as you wish. 


If the -dxb option 
each row of pixels 


isnot specified, the output of ppmtoacad isan AutoCAD sidefile N ormally, 
isrepresented by an AutoCAD line entity. If -poly is selected, the pixels are 


rendered as filled polygons. If the slide is viewed on a display with higher resolution than the source 
pixmap, this will cause the pixes to expand instead of appearing as discrete lines against the screen 


background color. 
take longer to disp 


Regrettably, this representation yields slide files that occupy more disc space and 
ay. 








Most AutoCAD di 


splay drivers can be configured to use any available color as the screan back- 


ground. Some users prefer a black screen background, others white, while splinter groups advocate 
burnt ocher, tawny puce, and shocking gray. D iscarding pixels whose closest AutoCAD color 
representation is equal to the background color can substantially reduce the size of the AutoCAD 


database or slide fi 
background color 
screen background 


e needed to represent a bitmap. If no -background color is specified, the screen 


isassumed to be black. Any AutoCAD color number may be specified as the 


; color numbers are assumed to specify the hues defined in the standard 





AutoCAD 256-co 


or palette. 


Because many AutoCAD users choose a white screen background, this option is provided as a 
short-cut. Specifying -white is identical in effect to -background 7. 

If the source pixmap had nonsquare pixels, the ratio of the pixd width to pixd haght should be 
specified as ratio. The resulting slide or D XB file will be corrected so that pixels on the AutoCAD 


screen will be squal 


re. For example, to correct an image made for a 320x200 VGA/M CGA screen, 


specify -aspect 0.8333, 
Restricts the colors in the output file to the eight RGB shades. 


All flags can be abbreviated to their shortest unique prefix. 


BUGS 


AutoCAD hasa fixed palette of 256 colors, distributed along the hue, lightness, and saturation axes. Pixmaps that contain 
many nearly identical colors, or colors not closely approximated by AutoC AD ’s palette may be poorly rendered. 


ppmtoacad works best if the system displaying its output supports the full 256 color AutoCAD palette. Monochrome, 
8-color, and 16-color configurations will produce less than optimal results. 


When creating aD XB file or aslide file with the -poly option, ppmtoacad finds both vertical and horizontal runs of identical 
pixds and consolidates them into rectangular regions to reduce the size of the output file This is effective for images with 
large areas of constant color, but it’s no substitute for true raster to vector conversion. In particular, thin diagonal lines are 
not optimized at all by this process. 


Output files can be huge 


SEE ALSO 
AutoCAD Reference M anual: “Slide File Format” and “Binary Drawing Interchange (D XB) Files’; ppm(5) 


AUTHOR 


John Walker 

Autodesk SA 

Avenue des C hamps-M ontants 14b 
CH-2074 MARIN 

Suisse/ Schweiz/Svizzera/Svizra/ Switzerland 
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Usenet: kelvin@Autodesk.com 
Fax: 038/33 88 15 
Voice 038/33 76 33 


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T his software is provided “as is” without express or implied warranty. 


AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 
10 Octobe 1991 
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ppmtobmp— C onvert a portable pixmap into aBM P file 


SYNOPSIS 

ppmtobmp [-windows ][-052][ppmfile] 
DESCRIPTION 

ppmtobmp reads a portable pixmap as input and produces a M icrosoft Windows or O S/2 BM P file as output. 
OPTIONS 


-windows Tals the program to produce a M icrosoft W indows BM P file 
-082 Tals the program to produce an O S/2 BMP file. (T his is the default.) 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 
bmptoppm(1), ppm(5) 


AUTHOR 
Copyright© 1992 by David W. Sanderson. 
26 Octobe 1992 


ppmtogif 


ppmtogif— Convert a portable pixmap into aGIF file 


SYNOPSIS 
ppmtogif [-interlace][-sort][-map mapfile][-transparent color ][ppmfile] 
DESCRIPTION 
ppmtogif reads a portable pixmap as input and produces a GIF file as output. 
OPTIONS 
-interlace Tells the program to produce an interlaced GIF file. 
-sort Produces a GIF file with a sorted colormap. 
-map mapfile Uses the colors found in the mapfile to createthecolormap in theGIF file, instead of the colors 


from ppmfile. Themapfil e can be any ppm file; all that matters isthe colors in it. If the colors in 
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ppmfile do not match those in mapfile, they are matched to a “best match.” A (much) better result 
can be obtained by using the following filter in advance: 


ppmquant -floyd -map mapfile 
-transparent color M ark the given color astransparent in theGIF file. Thecolor is specified asin ppmmake(1). N ote 
that this option outputs a GIF 89a format file, which might not be understood by your software. 


All flags can be abbreviated to their shortest unique prefix. 
SEE ALSO 


giftoppm(1), ppmquant(1), ppm(5) 


AUTHOR 
Based on airencop by D avid Rowley (mgardi@watdcsu.waterloo.edu). Lanpa-Ziv compression based on compress. 
Copyright© 1989 by J ef Poskanzer. 
30 June1993 


ppmtoicr 


ppmtoicr— Convert a portable pixmap into NCSA ICR format 
SYNOPSIS 


ppmtoicr [-windowname name][-expand expand][-display display][-rle][ppmfile] 


DESCRIPTION 


ppmtoicr reads a portable pixmanp file as input and produces an NCSA T ane Interactive C olor Raster graphic file as output. 
If ppmfile is not supplied, ppmtoicr will read from standard input. 

Interactive C olor Raster (ICR) is aprotocol for displaying raster graphics on workstation screens. T he protocol isimple 
mented in NCSA Telnet for the M acintosh version 2.3. TheICR protocol shares characteristics of the T ektronix graphics 
terminal emulation protocol. For example escape sequences are used to control the display. 

ppmtoicr will output the appropriate sequences to create a window of the dimensions of the input pixmap, create a colormap 
of up to 256 colors on the display, then load the picture data into the window. 


N ote that there is no icrtoppm tool; this transformation is one-way. 


OPTIONS 
-windownamename Output will be displayed in name. (Default isto use ppm-file or “untitled” if standard input is read.) 
-expandexpand © Output will be expanded on display by factor expand. (For example, a value of 2 will cause four pixels to be 
displayed for every input pixd.) 
-displaydisplay Output will be displayed on screen numbered display. 


-rle Use run-length encoded format for display. (T his will nearly always result in a quicker display, but may 
skew the colormap.) 


EXAMPLES 
This displays a ppm file using the protocol: 
ppmtoicr ppmfile 
This will create a window named ppmfile on the display with the correct dimensions for ppmfile, create and download a 


colormap of up to 256 colors, and download the picture into the window. The same effect may be achieved by the following 
sequence: 
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ppmtoicr ppmfile > filename 
cat filename 


To display aGIF file using the protocol in a window titled after the input file, zoom the displayed image by a factor of 2, 
and run-length encode the data: 
giftoppm giffile | ppmtoicr -w giffile -r -e 2 


BUGS 


The protocol uses frequent ffiush calls to speed up display. If the output is saved to afile for later display via cat, drawing 
will be much slower. In ether case, increasing the Blocksize limit on the display will speed up transmission substantially. 


SEE ALSO 
ppm(5) 
NCSA T dnet for the M acintosh, U niversity of Illinois at U roana-C hampaign (1989) 


AUTHOR 
Copyright© 1990 by Kanthan Pillay (svpillaye@Princeton.EDu), Princeton University Computing and Information T echnol- 
ogy 
30 July 1990 
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ppmtoilbm— Convert a portable pixmap into an ILBM file 


SYNOPSIS 


ppmtoilbm [-maxplanes|-mp N][-fixplanes| -fp N][-ham6} -ham8][-dcbits-dcplanesrgb] 
[-normal | -hamif | -hamforce | -24if|-24force; -dcif|-dcforce;-cmaponly] [-ecs;-aga] 
[- compress; -nocompress][-cmethod type][-mapppmfile] [-savemem] [ppmfile] 


DESCRIPTION 


ppmtoilbm reads a portable pixmap as input and produces an ILBM file as output. Supported ILBM types are the following: 


Norma ILBM swith 1-16 planes 

AmigaH AM with 3-16 planes 

24-bit 

Colormap (BuHD and cmap chunk only, nPlanes = 0) 

Unofficial direct color 1-16 planesfor each color component 

Chunks written: pBwHp, cmap, cAmG (only for HAM ), Bony (not for colormap files) unofficial pco chunk for direct color ILBM 


OPTIONS 
O ptions marked with (*) can be prefixed with no, for example, -nohamit. All optionscan be abbreviated to their shortest 
unique prefix. 
-maxplanes | -mp n (default 5, minimum 1, maximum 16) M aximum planes to writein anormal ILBM. If the 


pixmap does not fit into n planes, ppmtoilbm writes aH AM file (if -hamif is used), a 24-bit 
file (if -24i is used), a direct color file (if -dcif isused). or aborts with an error. 


-fixplanes | -fp n (min 1, max 16) If anormal ILBM is written, it will have exactly n planes. 


-hambits | -hamplanes n (default 6, min 3, max 16) Sdect number of planes for HAM picture Thecurrent Amiga 
hardware supports 6 and 8 planes, so for now you should only use this values. 


-normal (default) 


-hamif (*), -24if (*), 
-dcif (*) 

-hamforce (*), -24force (*), 
-dcforce (*) 


-dcbits | -dcplanes r g b 


-ecs (default) 
-aga 
-ham6 
-ham8 


-compress (*) (default), 
-cmethod none; byterun1 


-map ppmfile 


-cmaponly 


-Savemem 


BUGS 
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Turns off -hamif/-24if/-dcif, -hamforce/-24force/-dcforce and -cmaponly. Also sets 
compression type to byterun1. 


W rite a HAM /24-bit/direct color file if the pixmap does not fit into maxplanes planes. 
W ritea HAM /24-bit/direct color file. 


(default 5, min 1, max 16). Select number of bits for red, green, and blue in a direct color 
ILBM. 


Shortcut for: -hamplanes 6 -maxplanes 5 
Shortcut for: -hamplanes 8 -maxplanes 8 
Shortcut for: -hamplanes 6 -hamforce 
Shortcut for: -hamplanes 8 -hamforce 


Compress the Bopy chunk. The default compression method is byterun1. Compression 
requires building the|LBM imagein memory; turning compression off allows stream- 
writing of the image, but the resulting file will usually be 30 percent to 50 percent larger. 
Another alternative is the -savemem option; this will keen memory requirements for 
compression at aminimum, but is very slow. 

Write anormal ILBM using the colorsin ppmfile asthecolormap. T hecolormap file also 
determines the number of planes; a -maxplanes Or -fixplanes option is ignored. 

W rite a colormap file: only BvHD and cmap chunks, no Bopy chunk, nPlanes = 0. 

See the -compress option. 


HAM pictures will always get a grayscale colormap; a real color selection algorithm might give better results. On the other 
hand, this allows row-by-row operation on HAM images, and all HAM images of the same depth (number of planes) share a 
common colormap, which is useful for building HAM animations. 


REFERENCES 


AmigaROM Kernd Reference M anual— D evices (Third Edition), Addison Wesley, ISBN 0-201-56775-X 


SEE ALSO 


ppm(5), ilbmtoppm(1) 


AUTHORS 


Copyright© 1989 by J ef Poskanzer; modified O ctober 1993 by Ingo Wilken (Ingo.wilken@informatik.uni-oldenburg.de). 
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31 Octobe 1993 


ppmtomap— Extract all colors from a portable pixmap 


SYNOPSIS 


ppmtomap [-sort][-square] [ppmfile] 


DESCRIPTION 


ppmtomap reads a portable pixmap as input and produces a portable pixmap as output, representing acolormap of theinput 
file All n different colors found are put in an N X1 portable pixmap. This colormap file can be used as a mapfile for ppmquant 


OF ppmtogif. 
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OPTIONS 


-sort Produces a portable pixmap with the colorsin some sorted order 
-square  Producesa(more or less) square output file, instead of putting all colorson the top row 


All flags can be abbreviated to their shortest unique prefix. 
WARNING 


If you want to use the output file as a mapfilefor ppmtogif, you first have to do appmquant 256 because ppmtomap iS not 
limited to 256 colors (but to 65536). 


SEE ALSO 
ppmtogit(1), ppmquant(1), ppm(5) 


AUTHOR 
M arcel W ijkstra (wijkstra@fwi.uva.n1) 
Copyright© 1989 by J ef Poskanzer. 
11 August 1993 
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ppmtomitsu— C onvert a portable pixmap to aM itsubishi $340-10 file 


SYNOPSIS 
ppmtomitsu [-sharpness val ][-enlarge val ][-media string][-copy val ] 
[-dpi300][-tiny] [ppmfile] 

DESCRIPTION 


ppmtomitsu reads a portable pixmap as input and converts it into a format suitable to be printed by aM itsubishi S340-10 
printer, or any other M itsubishi color sublimation printer. 


TheM itsubishi $340-10 Color Sublimation printer supports 24-bit color. Images of the available sizes take so long to 
transfer that there is a fast method, enploying a lookup table that ppmtomitsu will use if there is amaximum of 256 colors in 
the pixmap. ppmtomitsu will try to position your image to the center of the paper, and will rotate your image for you if xsize 
is larger than ysize. If your image is larger than the media allows, ppmtomitsu will quit with an error message (W e decided 
that the media were too expensive to have careless users produce misprints.) After data transmission has started, the job can’t 
be stopped in a sane way without resetting the printer. T he printer understands putting together images in the printer’s 
memory; ppmtomitsu doesn’t utilize this as pnmcat and so on provide the same functionality and l& you view the result 
onscreen, too. The $340-10 is the lowest common denominator printer; for higher resolution printers, there's the dpise0 
option. The othe printers also support higher values for enlarge eg, but | don’t think that’s essential enough to warrant a 
change in the program. 


-sharpness 1-4 Sharpness designation. D efault is to use the current sharpness. 

-enlarge 1-3 Enlarge by a factor; default is 1 (no enlarge) 

-media A, A4, AS, A4S Designate the media you're using. D efault is 1184 x 1350, which will fit on any media. A is 1216 x 
1350, A4 is 1184 x 1452,AS iS1216 x 1650, and A4S is1184 x 1754. A warning: If you specify a 
different media than the printer currently has, the printer will wait until you put in the correct 
media or switch it off. 

-copy 1-9 The number of copies to produce. D efault is 1. 

-dpi300 D ouble the number of allowed pixels for aS3600-30 Printer in $340-10 compatibility mode. (The 
$3600-30 has 300dpi.) 
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-tiny M emory-safing, but always slow. The printer will get the data line-by-line in 24-bit. It’s probably a 
good idea to use this if your machine starts paging alot without this option. 


REFERENCES 
Mitsubishi Sublimation Full Color Printer S$340-10; Specifications of Parallel Interface L SP-F0232F 


SEE ALSO 


ppmquant(1), pnmscale(1), ppm(5) 


BUGS 


W edidn’t find any— yet. Besides, they're called features anyway :-) If you should find one, please email meat the following 
address. 


AUTHOR 
Copyright© 1992, 1993 by S. Petra Z adler, MPIFR Bonn, Germany (spz@specklec.mpifr-bonn.mpg.de). 
29 January 1992 
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ppmtopex— Convert a portable pixmap into aPCX file 


SYNOPSIS 


ppmtopcx [ppmfile] 


DESCRIPTION 


ppmtopex reads a portable pixmap as input and produces a PC X file as output. 


SEE ALSO 
pextoppm(1), ppm(5) 
AUTHOR 
Copyright © 1990 by M ichael Davidson. 
9 April 1990 
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ppmtopgm— C onvert a portable pixmap into a portable graymap 


SYNOPSIS 


ppmtopgm [ppmfile] 


DESCRIPTION 


ppmtopgm reads a portable pixmap as input and produces a portable graymap as output. T he quantization formula used is 
2997 +.587g+.114b. 


N ote that although thereis apgmtoppm program, it isnot necessary for simple conversions from pgm to ppm, because any ppm 
program can read pgm (and pbm ) files automagically. pgmtoppm is for colorizing a pgm file. Also, See ppmtorgb3 for a different 
way of converting color to gray. 
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QUOTE 


Cold-hearted orb that rules the night 
Removes the colors from our aight 
Red isgray, and yellow white 

But we decide which isright 

And which isa quantization error. 


SEE ALSO 
pgmtoppm(1), ppmtorgb3(1), rgb3toppm(1), ppm(5), pgm(5) 
AUTHOR 
Copyright© 1989 by J ef Poskanzer. 
23 D eamber 1988 


ppmtopit 
ppmtopi1— Convert a portable pixmap into an Atari D egas P!1 file 


SYNOPSIS 


ppmtopit [ppmfile] 


DESCRIPTION 


ppmtopi1 reads a portable pixmap as input and produces an Atari D egas P!1 file as output. 


SEE ALSO 


pittoppm(1), ppm(5), pbmtopi3(1), pi3topbm(1) 
AUTHOR 
Copyright© 1991 by Steve Baczyk (seb3egte.com) and J & Poskanzey. 
19 July 1990 


ppmtopict 
ppmtopict— Convert a portable pixmap into aM acintosh PICT file 


SYNOPSIS 


ppmtopict [ppmfile] 


DESCRIPTION 
ppmtopict reads a portable pixmap as input and produces aM acintosh PICT file as output. 


The generated file is only the data fork of a picture. You will need a program such aSmevert to generate a M acbinary or a 
BinH ex file that contains the necessary information to identify the fileasaPICT fileto MacOS. 


Even though PICT supports 2 and 4 bits per pixd, ppmtopict always generates an 8-bits-per-pixd file. 


BUGS 


The picture size field is only correct if the output is to a file because writing into this field requires seeking backwards on a 
file. H owever, the PICT documentation seems to suggest that this field is not critical anyway because it is only the lower 16 
bits of the picture size 
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SEE ALSO 


picttoppm(1), ppm(5), mcevert(1) 


AUTHOR 
Copyright© 1990 by Ken Yap (ken@cs.rocester.edu). 
15 April 1990 
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ppmtopj— Convet aportable pixmap to an HP Painted file 


SYNOPSIS 


ppmtopj [-gamma val ][-xpos val ][-ypos val ][-back dark{lite][-rle][-center] 
[-render none} snap | bw; dither |diffuse|monodither |monodiffuse;clusterdither | 
monoclusterdither] [ppmfile] 


DESCRIPTION 
ppmtopj reads a portable pixmap asinput and converts it into a format suitable to be printed by an HP Paint) printer. 


For best results, the input file should bein 8-color RGB form; that is, it should have only the eight binary combinations of 
full-on and full-off primaries. You could get this by sending the input file through ppmquant -map with amapfile such as 


P3 

81 

255 

@ 0 O 2550 0 02550 @ @ 255 

255 255 @ 255 @ 255 @ 255 255 255 255 255 


Or else you could US@ ppmdither -red 2 -green 2 -blue 2. 


OPTIONS 
-rle Run-length encode the image. (T his can result in larger images.) 
-back Enhance the foreground by indicating if the background is light or dark compared to the foreground. 
-render alg Use an internal rendering algorithm (default dither). 
-gamma int Gamma correct the image using the integer parameter as a gamma (default @). 
-center Center the image to an 8.5 by 11 page 
-XPOs pos M ove by pos pixels in the x direction. 
-ypos pos M ove by pos pixels in the y direction. 
REFERENCES 
HP Paint} & XL Color GraphicsPrinter U ser’s Guide 
SEE ALSO 
pnmdepth(1), ppmquant(1), ppmdither(1), ppm(5) 
BUGS 
M ost of the options have not been tested because of the price of the paper. 
AUTHOR 


Copyright© 1991 by Christos Zoulas. 
13 July1991 
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ppmtopjxl1— Convert a portable pixmap into an HP Paintjet XL PCL file 


SYNOPSIS 
ppmtopjxl [-nopack] [-gamma <n> ] [-presentation] [-dark] [-diffuse] 
[-cluster] [-dither] [-xshift <s> ] [-yshift <s> ] [-xshift <s> ] [-yshift <s> ] 
[-xsize;-width,-xscale <s> ] [-ysize;-height;-yscale <s> ] [ppmfile] 
DESCRIPTION 
ppmtopjx1 reads a portable pixmap as input and produces a PCL file suitable for printing on an HP Paintjet XL printer as 
output. 


The generated file is not suitable for printing on anormal Print} e& printer. The -nopack option generates a file that does not 
use the normal TIFF 4.0 compression method. Thisfile might be printable on anormal Paint) e& printer (not an XL). 


The -gamma option sets the gamma correction for the image. T he useful range for the Paint} et XL is approximately 0.6 
to 1.5. 


The rendering algorithm used for images can be altered with the -dither, -cluster, and -diffuse options. T hese options 
select ordered dithering, clustered ordered dithering, or error diffusion, respectivey. The-dark option can be used to 
enhance images with a dark background when they are reduced in size The-presentation option turns on presentation 
mode, in which two passes are made over the paper to increase ink density. This should be used only for images where 
quality is critical. 
The image can be resized by setting the -xsize and -ysize options. The parameter to ather of these options is interpreted as 
the number of dots to set the width or height to, but an optional dimension of pt (points), dp (decipoints), in (inches), or cm 
(centimeters) may be appended. If only one dimension is specified, the other will be scaled appropriate y. 





Theoptions -width and -height aresynonyms of -xsize and -ysize. 
The -xscale and -yscale options can alternatively be used to scale the image by asimple factor. 
The image can be shifted on the page by using the-xshift and -yshift options. These move the image the specified 
dimensions right and down. 
SEE ALSO 
ppm(5) 
AUTHOR 
Angus D uggan 
14 March 1991 
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ppmtopuzz— Convert a portable pixmap into an X11 puzzle file 


SYNOPSIS 


ppmtopuzz [ppmfile] 


DESCRIPTION 


ppmtopuzz reads a portable pixmap as input and produces an X11 puzzle file as output. A puzzle file is for use with the puzzle 
program included with the X11 distribution; puzzle’s -picture flag las you specify an image file 


ppmtos xd 


SEE ALSO 


ppm(5), puzzle(1) 
AUTHOR 


Copyright© 1991 by J ef Poskanzer. 
22 August 1990 


ppmtorgb3 
ppmtorgb3— Separate a portable pixmap into three portable graymaps 


SYNOPSIS 


ppmtorgb3 [ppmfile] 


DESCRIPTION 
ppmtorgb3 reads a portable pixmap as input and writes three portable graymaps as output, one each for red, green, and blue. 


The output filerames are constructed by taking the input filerame, stripping off any extension, and appending .red, .grn, 
and .blu. For example separating 1enna.ppm would result in 1lenna.red, lenna.grn, and lenna.blu. If theinput comes from 
stdin, the names are noname.red, noname.grn, and noname.blu. 


SEE ALSO 

rgbstoppm(1), ppmtopgm(1), pgmtoppm(1), ppm(5), pam(5) 
AUTHOR 

Copyright© 1991 by J ef Poskanzer. 

10 January 1991 
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ppmtosixel— Convert a portable pixmap into DEC sixel format 
SYNOPSIS 

ppmtosixel [-raw][-margin] [ppmfile] 
DESCRIPTION 


ppmtosixel reads a portable pixmap as input and produces sixd commands (SIX) as output. T he output is formatted for color 
printing, for example, fora DEC LJ 250 color inkje printer. 
If RGB values from the PPM filedo not have maxvai=100, the RGB values are rescaled. A printer control header and a color 


assignment table begin the SIX file Image data is written in a compressed format by default. A printer control footer ends 
the image file. 


OPTIONS 
-raw If specified, each pixel will be explicitly described in the image file. If -raw is not specified, output will default to 
compressed format in which identical adjacent pixds are replaced by repeat pixel commands. A raw file is often 
an order of magnitude larger than a compressed file and prints much slower. 
-margin If -margin isnot specified, the image will start at the left margin (of the window, paper, or whatever). If -margin is 
specified, a 1.5 inch left margin will offset the image. 
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PRINTING 


Generally, sixe files must reach the printer unfiltered. Usetheipr -x option or cat filename > /dev/tty0?. 


BUGS 
Upon rescaling, truncation of the least significant bits of RGB values may result in poor color conversion. If the original 
PPM maxval was greater than 100, rescaling also reduces the image depth. W hile the actual RGB values from the ppn file are 
more or less retained, the color palette of the LJ 250 may not match the colors on your screen. T his seems to be a printer 
limitation. 

SEE ALSO 
ppm(5) 

AUTHOR 
Copyright© 1991 by Rick Vind. 

26 April 1991 
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ppmtotga— Convert portable pixmap into aT rueVision T arga file 


SYNOPSIS 

ppmtotga [-mono}-cmap;-rgb][-norle][ppmfile] 
DESCRIPTION 

ppmtotga reads a portable pixmap as input and produces aT rueVision T arga file as output. 
OPTIONS 


-mono Forces T arga file to be of type 8-bit monochrome. Input must be a portable bitmap or a portable graymap. 

-cmap Forces T arga file to be of type 24-bit colormapped. Input must be a portable bitmap, a portable graymap, or a 
portable pixmap containing no more than 256 distinct colors. 

-rgb Forces T arga file to be of type 24-bit unmapped color. 

-norle Disables run-length encoding, in case you have aT arga reader that can’t read run-length encoded files. 


All flags can be abbreviated to their shortest unique prefix. If no file type is specified, the most highly constained compatible 
type is used, where monochrome is more constained than colormapped, which isin turn more constained than unmapped. 


BUGS 


Does not support all possible T arga file types. Should really bein pnm, not ppm. 


SEE ALSO 
tgatoppm(1), ppm(5) 
AUTHOR 
Copyright© 1989, 1991 by M ark Shand and J e Poskanzer. 
28 Octobe 1991 
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ppmtouil 


ppmtouil— Convert a portable pixmap into aM otif UIL icon file 


SYNOPSIS 


ppmtouil [-name uilname][ppmfile] 


DESCRIPTION 
ppmtouil reads a portable pixmap as input and produces aM otif UIL icon file as output. 


If the program was compiled with an rgb database specified, and an RGB value from the ppm input matches an RGB value 
from the database, then the corresponding color name mnemonic is printed in the UIL’s colormap. If no rgb database was 
compiled in, or if the RGB values don’t match, then the color will be printed with the #reB, #RRGGBB, #RRRGGGBBB, OF 
#RRRRGGGGBBBB hexadecimal format. 


OPTIONS 


-name Allows you to specify the prefix string that is printed in the resulting UIL output. If not specified, it will default to 
the filename (without extension) of the ppmfile argument. If -name is not specified and no ppmfile is specified 
(that is, piped input), the prefix string will default to the string "noname". 


All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 
ppm(5) 


AUTHOR 
Converted by J ef Poskanzer from ppmtoxpm.c, which is copyright© 1990 by M ark W. Snitily. 
31 August 1990 
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ppmtoxpm— C onvert a portable pixmap into an X11 pixmap 


SYNOPSIS 


ppmtoxpm [-name <xpmname>] [-rgb <rgb-textfile>][<ppmfile>] 


DESCRIPTION 
ppmtoxpm reads a portable pixmap as input and produces an X11 pixmap (version 3) as output that can be loaded directly by 
the XPM library. 


The -name option allows you to specify the prefix string which is printed in the resulting XPM output. If not specified, it will 
default to the filename (without extension) of the ppmfile argument. If -name is not specified and ppmfile is not specified 
(that is, piped input), the prefix string will default to the string "noname". 


The -rgb option allows you to specify an X11 rgb text file for the lookup of color name mnemonics. This RGB text fileis 
typically the /usr/1ib/X11/rgb.txt of theMIT X11 distribution, but any file using the same format may be used. When 
specified and an RGB value from the ppm input matches an RGB value from the <rgb-textfile>, then the corresponding 
color name mnenonic is printed in the XPM ‘scolormap. If -rgb isnot specified, or if the RGB values don’t match, then the 
color will be printed with the #rGB, #RRGGBB, #RRRGGGBBB, OF #RRRRGGGGBBBB hexadecimal format. 


All flags can be abbreviated to their shortest unique prefix. 
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For example, to convert the file dot (found in /usr/include/X11/bitmaps), from xbm to xpm, you could specify 


xbmtopbm dot | ppmtoxpm -name dot 


or, with an rgb text file (in the local directory) 
xbmtopbm dot | ppmtoxpm -name dot -rgb rgb.txt 


BUGS 


An option to match the closest (rather than exact) color name mnemonic from the rgb text would be a desirable enhance 
ment. 


Truncation of the least significant bits of an RGB value may result in nonexact matches when performing color name 
mnemonic lookups. 


SEE ALSO 
ppm(5) 
XPM M anual by Arnaud LeH ors (1ehors@mirsa. inria.fr). 


AUTHOR 


Copyright © 1990 by M ark W. Snitily. T his tool was developed for Schlumberger T echnologies, ATE Division, and with 
their permission is being made availableto the public with the above copyright notice and permission notice 


Upgraded to XPM 2 by Paul Breslaw, M ecasoft SA, Zurich, Switzerland (paul@mecazh.uu.ch); Thu, N ov 8, 16:01:17, 1990. 
Upgraded to XPM version 3 by Arnaud leH ors (lehors@mirsa.inria.fr). 
9 April 1991 
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ppmtoyuv— Convert a portable pixmap into an Abekas YUV file 
SYNOPSIS 


ppmtoyuv [ppmfile] 


DESCRIPTION 


ppmtoyuv reads a portable pixmap as input and produces an Abekas YU V file as output. 
SEE ALSO 
yuvtoppm(1), ppm(5) 


AUTHOR 


M arc Boucher (<marc@PostImage.com>), based on Example C onversion Program, A60/A64 Digital Video Interface M anual, 
page 69. Copyright© 1991 by DHD Post Image Inc. Copyright© 1987 by Abekas Video Systems Inc. 


25 March 1991 


ppmtoyuvsplit 


ppmtoyuvsplit— Convert a portable pixmap into three subsampled raw YU V files 


SYNOPSIS 


ppmtoyuvsplit basename [ppmfile] 


DESCRIPTION 


ppmtoyuvsplit reads a portable pixmap as input and produces three raw files— basename.Y, basename.U, and basename.V— aS 
output. T hese files are the subsampled raw YUV representation of the input pixmap, as required by the Stanford M PEG 
code. T he subsampling is done by arithmetic mean of 4 pixels colors into one The YUV values are scaled according to 
CCIR.601, as assumed by MPEG. 


SEE ALSO 
mpeg(1), ppm(5) 
AUTHOR 
Copyright© 1993 by Andre Beck (AndreBeck@IRS. Inf. TU-Dresden.de). Based On ppmtoyuv.c. 
9 Seotember 1993 


pr 


pr— Convert text files for printing 


SYNOPSIS 


pr [+PAGE] [-COLUMN] [-abcdfFmrtv] [-e[in-tab-char[in-tab-width]]] [-h header] 
[-ifout-tab-char[out-tab-width]]] [-1 page-length] [-n[number-separator[digits]]] 
[-o left-margin] [-s[column-separator]] [-w page-width] [--help] [-- version] [file...] 


DESCRIPTION 
This manual page documents the GN U version of pr. pr prints on the standard output a paginated and optionally 
multicolumn copy of the text files given on the command line, or of the standard input if no files are given or when the 
filename - is encountered. Form feeds in the input cause page breaks in the output. 


OPTIONS 

PAGE Begin printing with page Pace. 

-COLUMN Produce coLumn-column output and print columns down. The column width is automatically 
decreased as coLumn increases; unless you use the -w option to increase the page width as wal, this 
option might cause some columns to be truncated. 

-a Print columns across rather than down. 

-b Balance columns on the last page. 

-c Print control characters using hat notation (for example, *G); print other unprintable characters in 
octal backslash notation. 

-d D ouble-space the output. 

-e[in-tab-char Expand tabs to spaces on input. O ptional argument in-tab-char is the input tab character, default 

[in-tab-width]] tab. O ptional argument in-tab-width isthe input tab character's width, default s. 

-F, -f Use aform feed instead of newlines to separate output pages. 

-h header Replace the filename in the header with the string header. 

--help Print a usage message and exit with a nonzero status. 

-ifout-tab-char Replace spaces with tabs on output. O ptional argument out-tab-char isthe output tab character, 

[out-tab-width] ] default tab. O ptional argument out-tab-width is the output tab character's width, default s. 

-1 page-length Set the page length to page-!ength lines. T he default is 66. If page-! ength iSless than 10, the 


headers and footers are omitted, as if the-t option had been given. 
=m Print all files in parallel, onein each column. 
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-n[number -separator 
[digits] ] 


-o left- margin 


-s[column-separator ] 


-t 
-Vv 


--version 


-w page- width 


DS 


Precede each column with a linenumbe;; with parallel files, precede each line with a line number. 
Optional argument number-separator is the character to print afte: each number, default tab. 
Optional argument digits is thenumbe of digits pe linenumber, default 5. 


O ffset each line with amargin | eft- margin spaces wide The total page width is this offset plus the 
width set with the -w option. 


Do not print a warning message when an argument file cannot be opened. Failure to open afile 
still makes the exit status nonzero, however. 


Separate columns by the single character col umn- separator, default tab, instead of spaces. 


Do not print the 5-line header and the 5-linetrailer that are normally on each page, and do not fill 
out the bottoms of pages (with blank lines or form feeds). 


Print unprintable characters in octal backslash notation. 
Print version information on standard output then exit. 
Set the page width to page- width columns. T he default is 72. 


GNU Tet Utilitie 


ps— Report process status 


SYNOPSIS 


ps [-][lujsvmaxScewhrnu][txx][O[+}-]k1l[[+)-]k2...]] [pids] 


Thee are also two long options: 


--sortX[+;-]key[,[+)-]key[,---]] 


--help 


M orelong options are on the way... 


DESCRIPTION 


ps gives a napshot of the current processes. If you want a repetitive update of this status, use top. This man page documents 
the /proc-based version of ps, or tries to. 


COMMAND-LINE OPTIONS 


Command-line arguments may optionally be preceded by a -, but thereis no need for it. There are also some long optionsin 
GNU style see the following subsection for those 


Long format. 

User format: gives username and start time. 
Jobs format: pgid sid. 

Signal format. 

vm format. 

Displays memory information (combine with p flag to get number of pages). 
Forest family tree format for command line. 
Show processes of other users too. 

Show processes without controlling terminal. 
Add child cpu time and page faults. 
Command name from task struct. 

Show environment after command line and +. 


Olt; - TKI, E+, -1k20,.--1] 


Pies 


W ide output: don’t truncate command lines to fit on one line 

No header. 

Running procs only. 

Numeric output for user and wcHAN. 

Only procs with controlling tty xx; use for xx the same letters as shown in the Tt fidd. The 
tty name must be given immediately after the option, with no intervening space, for 
example, ps -tv1. 

Order the process listing according to the multilevel sort specified by the sequence of short 
keys from sorT KEYS, k1,k2,.... Default order specifications exist for each of the various 
formats of ps. T hese are overridden by a user-specified ordering. T he+ is quite optional, 
merely raterating the default direction on akey. - reverses direction only on the key it 
precedes. As with t and pids, theo option must be the last option in a single command 
argument, but specifications in successive arguments are catenated. 


pids List only the specified processes; they are comma-delimited. T he list must be given 
immediately after the last option in a single command-line argument, with no intervening 
space, for example ps -j1,4,5. Lists specified in subsequent arguments are catenated, for 
example, ps -11,23,4 5 6 will list all of the processes 1-6 in long format. 
LONG COMMAND-LINE OPTIONS 
T hese options are preceded by a double hyphen. 
--sortX[+!-]key[, Choose a multiletter key from the sortkeys section. x may be any convenient separator 
[+}-]key[,..-]] character. To beGN U-ish, use =. The + is really optional because default direction is 
increasing numerical or lexicographic order. Example: 
ps -jax -sort=uid, -ppid,+pid 
--help Get ahelp message that summarizes the usage and gives a list of supported sort keys. T his 
list may be more up-to-date than this man page 
SORT KEYS 


N ote that the values used in sorting are the internal values ps uses and not the “cooked” values used in some of the output 
format fidds. If someone wants to volunteer to write special comparison functions for the cooked values... ;-) 





Short Long D excription 

c cmd Simple name of executable 

Cc cmdline Full command line 

f flags Flags as in long format F field 
g pgrp Process group ID 

G tpgid Controlling tty process group ID 
j cutime Cumulative user time 

J cstime Cumulative systen time 

k utime User time 

K stime System time 

m min_flt N umber of minor page faults 
M maj_flt N umber of major page faults 
n cmin_flt Cumulative minor page faults 
N cmaj_flt Cumulative major page faults 
0 session Session ID 

p pid Process!D 


continues 
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Short Long D excription 

P ppid Parent process ID 

r rss Resident set size 

R resident Resident pages 

s size Memory size in kilobytes 

s share Amount of shared pages 

t tty The minor device number of tty 

T start_time Time process was started 

U uid User 1D number 

u user Username 

v vsize Total VM sizein bytes 

y priority Kernel scheduling priority 

FIELD DESCRIPTIONS 

PRI Thisis the counter fidd in thetask struct. It isthetimein Hz of the process's possible time slice. 

NI Standard U NIX nice value; a positive value means less cou time 

SIZE Virtual image size size of text+datatstack. 

RSS Resident set size kilobytes of program in memory. 

WCHAN N ame of the kernel function where the process is sleeping, with the sys stripped from the function name. If 
/boot/psdatabase does not exist, it isjust a hex number instead. 

STAT Information about the status of the process. The first fidd isr for runnable s for sleeping, o for uninterruptible 
sleep, T for stopped or traced, or z for a zombie process. T he second fidd contains w if the process has no resident 
pages. The third field isn if the process has a positive nice value (ni field). 

TT Controlling tty. 

PAGEIN Number of major page faults (page faults that cause pages to be read from disk, including pages read from the 
buffer cache). 

TRS Text resident size. 

SWAP Kilobytes (or pages if -p is used) on swap device 

SHARE Shared memory. 

UPDATING 


This proc-based ps works by reading thefilesin the proc filesystem, mounted on /proc. T hiSps does not need to be suid 
kmem or haveany privilegesto run. Do not givethisps any special permissons 


You will need to update the /boot/psdatabase file by running /usr/sbin/psupdate to get meaningful information from the 
wcHAN field. T his should be done every time you compile a new kernal. 


NOTES 


Themember used_math Of task_struct isnot shown, sincecrta.s checks to see if math is present. T his causes the math flag 
to be set for all processes, and so it is worthless. 


Programs swapped out to disk will be shown without command-line arguments, and unless thec option is given, in 
parentheses. 


scpu shows the cputime/realtime percentage. It will not add up to 100 percent unless you are lucky. It is time used divided 
by the time the process has been running. 


Thestze and ass fields don’t count the page tables and the task struct Of a proc; thisis at least 12k of memory that is 
always resident. s1ze is the virtual size of the proc (code+datatstack). 


psidtopgm 
BUGS 


tty names are hard-coded: virtual consoles arev1, v2,...; sfial lines areso ands1; pty’Sarepp0, ppl ... pg0,pql, «... 


AUTHORS 


ps was originally written by Branko Lankester (1lankeste@fwi.uva.n1) Michad K. Johnson (johnsonm@sunsite.unc.edu) 
rewrote it significantly to use the proc filesystem, changing afew things in the process. M ichad Shidds 
(mjshield@nyx.cs.du.edu) added the multiple-pids feature. Charles Blake(cb1ake@ucsd.edu) added multilevel sorting and is 
the current maintainer of the proc-ps suite 


Cohesve Systems 27 July 1994 


psbb 


psbb— Extract bounding box from PostScript document 


SYNOPSIS 


psbb file 


DESCRIPTION 


psbb reads file, which should bea PostScript document conforming to the document structuring conventions and looks for 
a %%BoundingBox comment. If it finds one, it prints a line 


11x lly urx ury 
on the standard output and exits with zero status. If it doesn’t find such a line or if the line is invalid, it prints a message and 
exits with nonzero status. 
SEE ALSO 
grops(1) 
Groff Verson 1.09, 6 August 1992 


psidtopgm 


psidtopgm— Convert PostScript image data into a portable graymap 


SYNOPSIS 


psidtopgm width height bits/sample [i magedata] 


DESCRIPTION 
psidtopgm reads the image data from a PostScript file as input and produces a portable graymap as output. 


This is avery simple and limited program, and is here only because so many people have asked for it. To use it you have to 
manually extract the readhexstring data portion from your PostScript file, and then give the width, height, and bits/sample 
on the command line. Before you attempt this, you should at least read the description of the image operator in the PostScript 
Language Reference M anual. 


It would probably not be too hard to write a script that uses this filter to read a specific variety of PostScript image, but the 
variation is too great to make a general-purpose reader. Unless, of course, you want to write a full-fledged PostScript 
interpreter... 


SEE ALSO 


pnmtops(1), pgm(5) 
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AUTHOR 
Copyright© 1989 by J ef Poskanzer. 
2 August 1989 


pstopnm 


pstopnm— Convert a PostScript file into a portable anymap 


SYNOPSIS 
pstopnm [-forceplain][-help][-11x s][-lly s ][-landscape] [-portrait][-nocrop] 
[-pbm |-pgm |-ppm][-urx s][-ury s][-verbose][-xborder n][-xmax n][-xsize f ] 
[-yborder f ][-ymax n][-ysize n] psfile[.ps] 


DESCRIPTION 


pstopnm reads a PostScript file as input and produces portable anymap files as output. This program is just a useful shell script 
that runs GhostScript to render a PostScript into one or more pnm files. pstopnm will create as many files as the number of 
pages in the PostScript document. If the input file is named pstile.ps, the name of the files will be pstileoo1.ppm, 
psfile002.ppm, and so on. 


The program maps a rectangular portion of the PostScript document into an image file according to the command-line 
options. T he selected area will always be centered in the output file and may have borders around it. T he image area to be 
extracted from the PostScript file and rendered into a portable anymap is defined by four numbers, the lower-left corner and 
the upper-right corner x and y coordinates. T hese coordinates are usually specified by the BoundingBox comment in the 
PostScript file header, but they can be overridden by the user by specifying one or more of the following flags: -11x, -11y, 
-urx, and -ury. The presence and thickness of a border to be left around the image area is controlled by the use of the flags 
-xborder and -yborder. If BoundingBox parameters are not found, and image area coordinates are not specified on the 
command line, default values are used. Unless both output file width and height are specified viathe-xsize and -ysize 
flags, the program will map the document into the output image by preserving its aspect ratio. 


OPTIONS 
-forceplain Forces the output file to be a plain (in other words, not “raw”) portable anymap. 
-help Prints the command syntax. 
-11x bx Sdectsbx asthe lower left corner x coordinate (in inches). 
-lly by Selects by asthe lower left corner y coordinate (in inches). 
-landscape Renders the image in landscape mode 
-portrait Renders the image in portrait mode. 
-nocrop D oes not crop the output image dimensions to match the PostScript image area dimensions. 
-pbm -pgm -ppm Sects the format of the output file. By default, all files are rendered as portable pixmaps (ppm format). 
-urx tx Sdectstx asthe upper-right corner x coordinate (in inches). 
-ury ty Sdectsty asthe upper-right corner y coordinate (in inches). 
-verbose Prints processing information to stdout. 


-xborder frac Specifies that the border width along theY axisshould befrac times the document width as specified by 
the bounding box comment in the PostScript file header. T he default value iso.1. 


-xmax xs Specifies that the maximum output image width should have a size less or equal to xs pixels (default: 612). 
-xsize xs Specifies that the output image width must be exactly xs pixds. 
if 


-yborder frac Specifies that the border width along theX axis should befrac times the document width as specified by 
the bounding box comment in the PostScript file header. T he default value iso.1. 


-ymax ys Specifies that the maximum output image height should have a size less or equal toys pixds (default: 792). 
-ysize ys Specifies that the output image height must be exactly ys pixels. 











if 
if 


pstree 
BUGS 


The program will produce incorrect results with PostScript files that initialize the current transformation matrix. In these 
cases, page translation and rotation will not have any effect. T o render these files, probably the best bet isto use the following 
flags: 


pstopnm -xborder @ -yborder @ -portrait -nocrop file.ps 
Additional flags may be needed if the document is supposed to be rendered on amedium different from letter-size paper. 
SEE ALSO 


gs(I), pstofits(I) 
COPYRIGHT 
Copyright© 1992 Smithsonian Astrophysical O bservatory. PostScript is a trademark of Adobe Systems Inc. 
AUTHOR 
Alberto Accomazzi, WIPL, C enter for Astrophysics 
28 D ecanber 1992 


pstree 

pstree— Display a tree of processes 
SYNOPSIS 

pstree [-a][-c][-h][-1][-p][-u][pid|user] 
DESCRIPTION 


pstree shows running processes as a tree. The tree is rooted at ather pia or init if pia is omitted. If a username is specified, 
all process trees rooted at processes owned by that user are shown. 


pstree visually merges identical branches by putting then in square brackets and prefixing them with the repetition count; 
for example, 


init-+-getty 


1-getty 
i getty 
'-getty 
becomes 
init--4*[getty] 
OPTIONS 
-a Show command-line arguments. | f the command line of a process is swapped out, that process is shown in 
parentheses. -a implicitly disables compaction. 
-c Disable compaction of identical subtrees. By default, subtrees are compacted whenever possible. 
-h Highlight the current process and its ancestors. This is ano-op if the terminal doesn’t support highlighting or if 
neither the current process nor any of its ancestors are in the subtree being shown. 
=1 Display long lines. By default, lines are truncated to the display width or 132 if outputis sent to anon-tty or if 
the display width is unknown. 
-p Show pids. pids are shown as decimal numbers in parentheses after each process name. -p implicitly disables 
compaction. 
-u Show uid transitions. W heneve the uia of aprocess differs from the uia of its parent, the new uid is shown in 


parentheses after the process name 
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FILES 


/proc Location of the proc filesystem 


AUTHOR 


Werner Almesberger (almesber@di.epf1.ch) 


SEE ALSO 
ps(1), top(1) 
Linux, 11 October 1994 


psupdate 


psupdate— U pdate the ps database of kernel offsets 


SYNOPSIS 


psupdate [system path] 


DESCRIPTION 


psupdate updates the /boot /psdatabase file to correspond to the current kernel image system mapfile /usr/src/linux/vmlinux 
by default. 


OPTIONS 


If your system mapfile is not /usr/src/linux/vmlinux, you May give the name of an alternate mapfile on the command line 


FILES 


/boot/psdatabase 
/usr/src/linux/vmlin 


SEE ALSO 
ps(1), top(1), utmp(5) 


AUTHORS 


Original code written by Branko Lankaster, horribly munged by M ichad K. Johnson in a desperate effort to add /etc/ 
psdatabase support to procps. Someday, it should be rewritten, and the support in ps for alternate namelists added. Anyone 
want to volunteer to be added to the “Authors” section? 


Cohesive Systems, 15 September 1993 


qrttoppm 


qrttoppm— Convert output from the Q RT ray tracer into a portable pixmap 


SYNOPSIS 


qrttoppm [qrtfile] 


DESCRIPTION 


qrttoppm reads aQRT file asinput and produces a portable pixmap as output. 


ranlib 437 


SEE ALSO 
ppm(5) 
AUTHOR 
Copyright© 1989 by J ef Poskanzer. 
25 August 1989 
quota 
quota— D isplay disk usage and limits 
SYNOPSIS 
quota [ -guv ; q ] 
quota [ -uv |} q ] user 
quota [ -gv | q ] group 
DESCRIPTION 
quota displays users’ disk usage and limits. By default, only the user quotas are printed. 
-g Print group quotas for the group of which the user is amember. The optional -u flag is equivalent to the default. 
-Vv W ill display quotas on filesystems where no storage is allocated. 
-q Print a more terse message, containing only information on filesystems where usage is over quota. 


Specifying both -g and -u displays both the user quotas and the group quotas (for the user). 


Only the superuser may use the -u flag and the optional user argument to view the limits of other users. N on-superusers can 
use the -g flag and optional group argument to view only the limits of groups of which they are members. 


The -q flag takes precedence over the -v flag. 


quota reports the quotas of all the filesystems listed in /etc/fstab. For filesystems that are N FS-mounted, acall to the 
rpc.rquotad on the server machine is performed to get the information. If quota exits with anonzero status, one or more 
filesystems are over quota. 


FILES 

quota.user Located at the filesystem root with user quotas 

quota. group Located at the filesystem root with group quotas 

/etc/fstab To find filesystem names and locations 
SEE ALSO 

quotact1(2), fstab(5), edquota(8), quotacheck(8), quotaon(8), repquota(8) 

8 January 1993 

ranlib 

ranlib— Generate index to archive 
SYNOPSIS 


ranlib [ -vj-V] archive 
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DESCRIPTION 
ranlib generates an index to the contents of an archive and storesit in the archive T he index lists each symbol defined by a 
member of an archivethat is a relocatable object file. 


You May use nm -s Of nm --print-armap to list this index. 


An archive with such an index speeds up linking to the library, and allows routines in the library to call each other without 
regard to thar placement in the archive 


TheGNU ranlib program is anothe form of GN U ar; running ranlib is completely equivalent to executing ar -s. 


OPTIONS 

-v Print the version number of ranlib and exit 
SEE ALSO 

binutils entry in info; TheGNU Binary Utilities Roland H. Pesch (October 1991); ar(1); nm(1). 
COPYING 


Copyright© 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus support, 5 N ovember 1991 


rasttopnm 


rasttopnm— Convert a Sun raster file into a portable anymap 


SYNOPSIS 


rasttopnm [rastfile] 


DESCRIPTION 


rasttopnm reads a Sun raster file as input and produces a portable anymap as output. T he type of the output file deoends on 
the input file— if it’s black and white, a pbm file is written; else if it’s grayscale, a pgm file; else appm file. The program tals you 
which type it is writing. 


SEE ALSO 


pnmtorast(1), pnm(5) 


AUTHOR 
Copyright © 1989, 1991 byJef Poxanzer. 


13 January 1991 


rawtoppm 


rawtopgm 

rawtopgm— C onvert raw grayscale bytes into a portable graymap 
SYNOPSIS 

rawtopgm [-headerskip N][-rowskip N][-tb;-topbottom][width height ][i magedata] 
DESCRIPTION 


rawtopgm reads raw grayscale bytes asinput and produces a portable graymap as output. T he input file is just grayscale bytes. 
If you don’t specify the width and height on the command line the program will check the size of the image and try to make 
a quadratic image of it. It is an error to supply a non-quadratic image without specifying width and height. T he maxvai is 
assumed to be 255. 


OPTIONS 
-headerskip If the file has a header, you can use this flag to skip over it. 
-rowskip If there is padding at the ends of the rows, you can skip it with this flag. N ote that rowskip can bea real 


number. Amazingly, | once had an image with 0.376 bytes of padding per row. This turned out to be due 
to afile transfer problem, but | was still able to read the image. 

-tb -topbottom Flips the image upside down. The first pixd in a pgm file isin the lowe-left corner of the image For 
conversion from images with the first pixd in the upper-left corner (for example, the M olecular D ynamics 
and Leica confocal formats), this flips the image right. This is equivalent to rawtopgm [file] | pnmflip 
-tb. 


BUGS 
If you don’t specify the image width and haght, the program will try to read the entire image to amemory buffer. If you get 
a message that states that you are out of memory, try to specify the width and height on the command line Also, the -tb 
option consumes much memory. 


SEE ALSO 
pgm(5), rawtoppm(1), pnmflip(1) 
AUTHORS 
Copyright© 1989 by J ef Poskanzer; modified J une 1993 by Oliver T repte (oliver@fysik4.kth.se). 
15 June1993 
rawtoppm 
rawtoppm— Convert raw RGB bytesinto aportable pixmap 
SYNOPSIS 
rawtoppm[ -headerskip N][-rowskip N][-rgb;-rbg}-grb |-gbr{-brg;-bgr ] 
[-interpixel|-interrow] width height [imagedata] 
DESCRIPTION 


rawtoppm reads raw RGB bytes asinput and produces a portable pixmap as output. T heinput file is just RGB bytes. You have 
to specify the width and height on the command line because the program obviously can’t get then from the file. The maxval 
is assumed to be 255. If the resulting image is upside down, run it through pnmflip -tb. 
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OPTIONS 

-headerskip If the file has a header, you can use this flag to skip over it. 

-rowskip If there is padding at the ends of the rows, you can skip it with this flag. 

-rgb -rbg -grb -gbr -brg -bgr These flags le you specify alternate color orders. The default is -rgb. 

-interpixel -interrow T hese flags let you specify how the colors are interleaved. T he default is -interpixel, 
meaning interleaved by pixel. A byte of red, a byte of green, and a byte of blue or whatever 
color order you specified. -interrow means interleaved by row— a row of red, a row of 
green, a row of blue, assuming standard RGB color order. An -interplane flag— all the red 
pixds, then all the green, then all the blue— would be an obvious extension, but is not 
implenented. You could get the same effect by splitting the file into three parts (perhaps 
using da), turning each part into aPGM file with rawtopgm, and then combining then with 
rgb3toppm. 

SEE ALSO 
ppm(5), rawtopgm(1), rgb3toppm(1), pnmfiip(1) 
AUTHOR 


Copyright© 1991 by J ef Poskanzer. 
6 February 1991 


rcp— Remote file copy 
SYNOPSIS 

rep [-px] [-k realm] filel file2 

rep [-px] [-r] [-k Ar realm] file ... directory 
DESCRIPTION 


rcp copies files between machines. Each file or directory argument is either a remote filename of the form rnamee@rhost: path, 
or alocal filename (containing no : characters, or a/ before any : characters). 


-r If any of the source files are directories, rcp copies each subtree rooted at that name; in this case the destination 
must bea directory. 
-p Causes rcp to attempt to preserve (duplicate) in its copies the modification times and modes of the source files, 


ignoring the umask . By default, the mode and owne of fil e2 are preserved if it already existed; otherwise, the 
mode of the source file modified by the umask 2 on the destination host is used. 


-k Requests rcp to obtain tickets for the remote host in realm real m instead of the remote host's realm as determined 
by krb_realmofhost 3. 
-X Turns on DES encryption for all data passed by rcp. This may impact response time and CPU utilization, but 


provides increased security. 


If path is not a full pathname it isinterpreted relative to the login directory of the specified user ruser On rhost, Or your 
current username if no other renote username is specified. A path on a remote host may be quoted (using \, “, or ‘) so that 
the meta characters are interpreted remotely. 


rcp doesnot prompt for passwords; it performs remote execution via rsh(1), and requires the same authorization. 
rcp handles third-party copies, where nether source nor target files are on the current machine. 


SEE ALSO 
cep(1), ftp(1), rsh(1), rlogin(1) 


HISTORY 
The rcp command appeared in BSD 4.2 . The version of rcp described here has been ramplenented with Kerberos in BSD 
4,3 Reno. 


BUGS 
D oesn’t detect all cases in which the target of a copy might bea file when only a directory should be legal. 
Is confused by any output generated by commandsin a or file on the remote host. 


The destination username and hostname may have to be specified as rhost .rname when the destination machine is running 
the BSD 4.2 version of rcp. 


BSD 4.3r, 27 July1991 


rcs 

res— ChangeRCS file attributes 
SYNOPSIS 

res options file ... 
DESCRIPTION 


res Creates new RCS files or changes attributes of existing ones. An RCS file contains multiple revisions of text, an access list, 
a change log, descriptive text, and some control attributes. For res to work, the caller's login name must be on the access 
list— unless the access list is anpty, the caller is the owner of the file or the superuser, or the -i option is present. 


Pathnames matching an RCS suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(1). 
Revision numbers usethe syntax described in ci(1). 


OPTIONS 

-i Create and initialize anew RCS file, but do not deposit any revision. If the RCS file has no path prefix, try 
to place it first into the subdirectory ./rcs, and then into the current directory. If the RCS file already 
exists, print an error message. 

-al ogins Append the login names appearing in the comma-separated list | ogins to the access list of theRCS file 

-Aol dfile Append the access list of o! dfile to the access list of the RCS file 

-e[logins] Erase the login names appearing in the comma-separated list | ogi ns from the access list of theRCS file If 
logins iSomitted, erase the entire access list. 

-b[rev] Se the default branch torev.If rev is omitted, the default branch is reset to the (dynamically) highest 
branch on the trunk. 

-cstring Set the comment leader to string. An initial ci,or an rcs -i without -c, guesses the comment leader from 


the suffix of the working filename 


This option is obsolescent, since RCS normally uses the preceding $Logs line’s prefix when inserting log lines during 
checkout (see co(1)). H owever, older versions of RCS use the comment leader instead of the $Logs line’s prefix, so if you plan 
to access a file with both old and new versions of RCS, make sure its comment leader matches its sLog$ line prefix. 


-ksubst Sé& the default keyword substitution to subst. The effect of keyword substitution is described in co(1). 
Giving an explicit -k option to co, resdiff, and rcesmerge overrides this default. Beware rcs -kv, because 
-kv isincompatible with co -1. Usercs -kkv to restore the normal default keyword substitution. 


Part |: User Commands 


-l[rev] 


-u[rev] 


-mr ev: ms g 
-M 


-nname[:[rev]] 


-Nname[:[rev ]] 


-orange 


-q 
-I 


-sstate[:rev] 


-t[file] 


-t-string 
-T 


-V 
-Vn 
-xsuffixes 


-zz0ne 


Lock the revision with number rev. If a branch is given, lock the latest revision on that branch. If rev is 
omitted, lock the latest revision on the default branch. Locking prevents overlapping changes. | f someone 
else already holds the lock, the lock is broken as with rcs -u. 

Unlock the revision with number rev. If a branch is given, unlock the latest revision on that branch. If rev 
is omitted, renove the latest lock held by the caller. N ormally, only the locker of a revision can unlock it. 
Somebody else unlocking a revision breaks the lock. T his causes a mail message to be sent to the original 
locker. The message contains a commentary solicited from the breaker. The commentary is terminated by 
end-of-file or by aline containing a period by itsalf. 

Sé& locking to strict. strict locking means that the owner of an RCS fileis not exenpt from locking for 
checkin. This option should be used for files that are shared. 

Sé& locking to non-strict. non-strict locking means that the owner of a file need not lock a revision for 
checkin. This option should not be used for files that are shared. W hether default locking is strict is 
determined by your system administrator, but it isnormally strict. 

Replace revision r ev's log message with ms g. 

Do not send mail when breaking somebody dse’s lock. This option is not meant for casual use; it is meant 
for programs that warn users by other means, and invoke rcs -u only aSalow-leva lock-breaking 
operation. 

Associate the symbolic name name with the branch or revision rev. D dete the symbolic nameif both : and 
rev are omitted; otherwise, print an error message if name is already associated with another number. If rev 
is symbolic, it is expanded before association. Arev consisting of a branch number followed by a period 
stands for the current latest revision in the branch. A : with an enpty rev stands for the current latest 
revision on the default branch, normally the trunk. For example, rcs -nname: RCS/* associates name with 
the current latest revision of all the named RCS files; this contrasts with res -nname :$ RCS/*, which 
associates name with the revision numbers extracted from keyword strings in the corresponding working 
files. 

Act like -n, except override any previous assignment of name. 

D eletes (“outdates”) the revisions given by range. A range consisting of a single revision number means 
that revision. A range consisting of a branch number means the latest revision on that branch. A range of 
the form revi:rev2 meansrevisionsrev1 torev2 on thesame branch, :rev meansfrom the beginning of 
the branch containingrev up to and includingrev, andrev: means from revision rev to theend of the 
branch containingrev. N one of the outdated revisions can have branches or locks. 

Run quietly; do not print diagnostics. 

Run interactively, even if the standard input is not aterminal. 

Se the state attribute of the revisionrev tostate.lfrev isabranch number, assume the latest revision on 
that branch. If rev is omitted, assume the latest revision on the default branch. Any identifier is acceptable 
forstate. A useful set of states isexp (for experimental), stab (for stable), and Re1 (for released). By 
default, ci(1) sets the state of a revision to Exp. 

W rite descriptive text from thecontents of the named file into theRCS file, ddeting the existing text. 
Thefile pathnamecannot begin with -. If file isomitted, obtain thetext from standard input, 
terminated by end-of-file or by a line containing a period by itself. Prompt for the text if interaction is 
possible see -1. With -i, descriptive text is obtained even if -t isnot given. 

W rite descriptive text from thestring into theRCS file, deleting the existing text. 

Preserve the modification timeon theRCS file unless a revision is removed. This option can suppress 
extensive recompilation caused by a make(1) dependency of some copy of the working file on the RCS file 
Use this option with care; it can suppress recompilation even when it is needed, that is, when a change to 
the RCS file would mean a change to keyword strings in the working file 

Print RCS's version numbe.. 

Emulate RCS version n. See co(1) for details. 

Usesuffixes to characterizeRCS files. See ci(1) for details. 


Usezone asthe default timezone This option has no effect; it is present for compatibility with othe RCS 
commands. 


resclean 


At least one explicit option must be given, to ensure compatibility with future planned extensions to the rcs command. 


COMPATIBILITY 
The -brev option generates an RCS file that cannot be parsed by RCS version 3 or earlier. 
The-ksubst options (except -kkv) generate an RCS file that cannot be parsed by RCS version 4 or earlier. 
Usercs -vn to makean RCS file acceptable to RCS version n by discarding information that would confuse version n. 
RCS version 5.5 and earlier does not support the -x option, and requires a ,v suffix on an RCS pathname. 


FILES 
res accesses files much as ci(1) does, except that it uses the effective user for all accesses, it does not write the working file or 
its directory, and it does not even read the working file unless a revision number of $ is specified. 

ENVIRONMENT 


RCSINITF1[:rev] Options prepended to the argument list, separated by spaces. See ci(1) for details. 


DIAGNOSTICS 


TheRCS pathname and the revisions outdated are written to the diagnostic output. The exit status is zero if and only if all 
operations were successful. 


IDENTIFICATION 


Author: Walter F. Tichy. 

M anual Page Revision: 5.13; Release D ate: 1995/06/05. 
Copyright 1982, 1988, 1989 W alter F. Tichy. 

Copyright 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 


SEE ALSO 
resintro(1), co(1), ci(1), ident(1), resclean(1), resdift(1), rcsmerge(1), rlog(1), resfile(5) 
“RCS—A System for Version Control” by Walter F. Tichy, Software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

BUGS 


A catastrophe (for example, a system crash) can cause RCS to leave behind a semaphore file that causes later invocations of 
RCS to claim that theRCS fileis in use To fix this, renove the semaphore file A sanaphore file's name typically begins 
with acomma or ends with an underscore 


The separator for revision rangesin the -o option used to be - instead of :, but this leads to confusion when symbolic names 
contain -. For backwards compatibility, res -o still supports the old - separator, but it warns about this obsolete use. 


Symbolic names need not refer to existing revisions or branches. For example, the -o option does not remove symbolic names 
for the outdated revisions, you must use -n to renove the names. 


GNU, 5 June1995 


resclean 


resclean— Clean up working files 


SYNOPSIS 


resclean [options ][file ...] 


Part |: User Commands 


DESCRIPTION 


resclean renoves files that are not being worked on. rcsclean -u also unlocks and removes files that are being worked on 
but have not changed. 


Foreach file given, resclean compares the working file and a revision in the corresponding RCS file If it finds a difference, 
it does nothing. O therwise, it first unlocks the revision if the -u option is given, and then renoves the working file unless the 
working file is writable and the revision is locked. It logs its actions by outputting the corresponding res -u and rm -f 
commands on the standard output. 


Files are paired as explained in ci(1). If nofile is given, all working files in the current directory are cleaned. Pathnames 
matching an RCS suffix denote RCS files; all others denote working files. 


The number of the revision to which the working file is compared may be attached to any of the options-n, -q, -r, or -u. If 
no revision number is specified, then if the -u option is given and the caller has onerevision locked, rcsclean uses that 
revision; otherwise, rcsclean uses the latest revision on the default branch, normally the root. 


resclean iSuseful for clean targets in makefiles. See also resditt(1), which prints out the differences, and ci(1), which 
normally reverts to the previous revision if a file was not changed. 


OPTIONS 

-ksubst Usesubst -style keyword substitution when retrieving the revision for comparison. See co(1) for details. 

-n[rev] Do not actually renove any files or unlock any revisions. Using this option will tell you what rcsclean 
would do without actually doing it. 

--q{rev] Do not log the actions taken on standard output. 

--r[rev] This option has no effect other than specifying the revision for comparison. 

-T Preserve the modification time on the RCS file even if the RCS file changes because a lock is removed. 
This option can suppress extensive recompilation caused by a make(1) dependency of some other copy of 
the working file on the RCS file Use this option with care it can suppress recompilation even when it is 
needed, that is, when thelock removal would mean a change to keyword strings in the other working file 

-u[rev] Unlock the revision if it is locked and no difference is found. 

-V Print RCS's version numbe.. 

-Vn Emulate RCS version n. See co(1) for details. 

-xsuf fixes Usesuffixes to characterize RCS files. See ci(1) for details. 

-zz0ne Usezone asthe timezone for keyword substitution; see co(1) for details. 

EXAMPLES 


resclean *.c *.h removesall working files endingin .c or .h that were not changed since their checkout. 
resclean renoves all working filesin the current directory that were not changed since ther check-out. 


FILES 


resclean accesses files much as ci(1) does. 


ENVIRONMENT 


RCSINIT Options prepended to the argument list, separated by spaces. A backslash escapes spaces within an option. The 
RCSINIT Options are prepended to the argument lists of most res commands. U seful rcsin1T optionsinclude -q, 
-V, -x, and -z. 


DIAGNOSTICS 


The exit status is zero if and only if all operations were successful. M issing working files and RCS files are silently ignored. 


readiff 


IDENTIFICATION 
Author: Walter F. Tichy. 
M anual Page Revision: 1.12; Release D ate: 1993/11/03. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993 Paul Egget. 
SEE ALSO 
ci(1), co(1), ident(1), res(1), resdift(1), resintro(1), resmerge(1), rlog(1), resfile(5) 
“RCS—A System for Version Control” by Walter F. Tichy, Software Practice & Experience 15, 7 (July 1985), pages 
637-654. 
BUGS 


At least onefi!e must begiven in older UNIX versionsthat do not provide the needed directory scanning operations. 
GNU, 3 Novenber 1993 


rcesdiff 


resdiff— Compare rcs revisions 


SYNOPSIS 


resdiff [ -ksubst ][-q ][-rrevl [ -rrev2 ]][-T ][-V[n]][-xsuffixes ][-zzone ] 
[diff options ] file... 
DESCRIPTION 
resdiff runs diff(1) to compare two revisions of each RCS file given. 
Pathnames matching an rcs suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(1). 


The option -q suppresses diagnostic output. Zero, one, or two revisions may be specified with -r. The option -ksubst affects 
keyword substitution when extracting revisions, as described in co(1); for example, -kk -r1.1 -r1.2 ignores differences in 
keyword values when comparing revisions 1.1 and 1.2. To avoid excess output from locker name substitution, -kkv1 is 
assumed if at most one revision option is given, no -k option is given, -kkv isthe default keyword substitution, and the 
working file’s mode would be produced by co -1. See co(1) for details about -T, -v, -x, and -z. O therwise, all options of 
diff(1) that apply to regular files are accepted, with the same meaning as for diff. 


If both revi and rev2 areomitted, rcsaitf compares the latest revision on the default branch (by default the trunk) with the 
contents of the corresponding working file T his is useful for determining what you changed since the last checkin. 


If revi isgiven, but rev2 isomitted, resaiff compares revision rev1 of theRCS file with the contents of the corresponding 
working file. 


If both revi andrev2 are given, resdiff Compares revisionsrev1 andrev2 of theRCS file 
Both revi andrev2 may be given numerically or symbolically. 


EXAMPLE 
Thecommand 
resdiff f.c 


compares the latest revision on the default branch of the RCS file to the contents of the working file f.c. 


ENVIRONMENT 


RCSINIT Options prepended to the argument list, separated by spaces. See ci(1) for details. 


Part |: User Commands 


DIAGNOSTICS 


Exit status is @ for no differences during any comparison, 1 for some differences, 2 for trouble. 


IDENTIFICATION 


Author: Walter F. Tichy. 

M anual Page Revision: 5.5; Release D ate: 1993/11/03. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993 Paul Egget. 


SEE ALSO 
ci(1), co(1), ditt(1), ident(1), res(1), resintro(1), resmerge(1), rlog(1) 
“RCS—A System for Version Control” by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 


637-654. 
GNU, 3 November 1993 
resfreeze 
resfreeze— Freeze a configuration of sources checked in unde RCS 
SYNOPSIS 
resfreeze [name ] 
DESCRIPTION 


resfreeze assigns a symbolic revision number to a set of RCS files that form a valid configuration. 


Theideaisto run rcsfreeze each time anew version is checked in. A unique symbolic name(c_number, where number iS 
increased each time rcsfreeze is run) is then assigned to the most recent revision of each RCS file of the main trunk. 


An optional name argument to resfreeze gives a symbolic nameto the configuration. T heunique identifier is still generated 
and is listed in the log file, but it will not appear as part of the symbolic revision namein the actual RCS files. 


A log message is requested from the user for future reference. 
The shdl script works only on all RCS files at one time. All changed files must be checked in already. Run rcsclean(1) first 
and see whether any sources remain in the current directory. 


FILES 


RCS/.rcsfreeze.ver Version number 
RCS/.rcsfreeze.log Log messages, most recent first 


AUTHOR 
Stephan V. Bechtolsheim 


SEE ALSO 
co(1), res(1), resclean(1), riog(1) 


BUGS 
resfreeze does not check whether any sources are checked out and modified. 
Although both sourcefilenames and RCS filenames are accepted, they are not paired as usual with res commands. 
Error checking is rudimentary. 


rcsintro 447 


resfreeze iSjust an optional example shell script, and should not be taken too seriously. See cvs for amore complete 
solution. 


GNU, 3 November 1990 


resintro 


resintro— Introduction to res commands 


DESCRIPTION 


The Revision Control Systan (RCS) manages multiple revisions of files. RCS automates the storing, retrieval, logging, 
identification, and merging of revisions. RCS is useful for text that is revised frequently; for example programs, documenta- 
tion, graphics, papers, and form letters. 


The basic user interface is extremely simple. The novice only needs to learn two commands: ci(1) and co(1). ci, short for 


check in, deposits the contents of a file into an archival file called an RCS file. An RCS file contains all revisions of a 
particular file. co, short for check out, retrieves revisions from an RCS file. 


FUNCTIONS OF RCS 


Store and retrieve multiple revisions of text. RCS saves all old revisionsin a space-efficient way. Changes no longer destroy 
the original because the previous revisions remain accessible. Revisions can be retrieved according to ranges of revision 
numbers, symbolic names, dates, authors, and states. 

Maintain a complete history of changes. RCS logs all changes automatically. Besides the text of each revision, RCS stores 
the author, the date and time of checkin, and a log message summarizing the change The logging makes it easy to find out 
what happened to amodule without having to compare source listings or having to track down colleagues. 

Resolve access conflicts. W hen two or more programmers wish to modify the same revision, RCS alerts the programmers 
and prevents one modification from corrupting the othe. 

Maintain a tree of revisions. RCS can maintain separate lines of development for each module. It stores a tree structure that 
represents the ancestral rdationships among revisions. 

Merge revisions and resolve conflicts. T wo separate lines of development of a module can be coalesced by merging. If the 
revisions to be merged affect the same sections of code, RCS alerts the user about the overlapping changes. 

Control releases and configurations Revisions can be assigned symbolic names and marked as released, stable, experimen- 
tal, and so on. With these facilities, configurations of modules can be described simply and directly. 

Automatically identify each revision with name, revision number, creation time, author, and so on. T he identification 
is like a stamp that can be embedded at an appropriate place in the text of arevision. The identification makesit simple to 
determine which revisions of which modules make up a given configuration. 

Minimize secondary storage RCS needs little extra space for the revisions (only the differences). If intermediate revisions 
are dd eed, the corresponding deltas are compressed accordingly. 


GETTING STARTED WITH RCS 


Suppose you have a file f.c that you wish to put under control of RCS. If you have not already done so, make an rcs 
directory with the command: 


mkdir RCS 
Then invoke the check in command: 
Cae fC 


This command creates an RCS filein thercs directory, storest.c into it asrevision 1.1, and deletes ¢.c. It also asks you for 
a description. The description should be a synopsis of the contents of the file. All later check in commands will ask you for a 
log entry, which should summarize the changes that you made. 


Part |: User Commands 


Files in thercs directory are called RCS files; the others are called working files. To get back the working filet.c in the 
previous example, use the check out command: 


co f.c 
This command extracts the latest revision from the RCS file and writes it into t.c. If you want to edit t.c, you must lock it 
as you check it out with the command: 


co -l f.c 


You can now edit f.c. 

Suppose after some editing you want to know what changes that you have made. The command: 

resdiff f.c 

tells you the difference between the most recently checked-in version and the working file. You can check the file back in by 
invoking 

ci f.c 

This increments the revision number properly. 

If ci. complains with the message: 


ci error: no lock set by your name 


then you havetried to check in a file even though you did not lock it when you checked it out. Of course, it istoo late now 
to do the checkout with locking, because another checkout would overwrite your modifications. Instead, invoke 


res -l f.c 


This command will lock the latest revision for you, unless somebody dise got ahead of you already. In that case, you'll have to 
negotiate with that person. 


Locking assures that you, and only you, can check in the next update, and avoids nasty problems if several people work on 
the same file. Even if arevision is locked, it can still be checked out for reading, compiling, and so on. All that locking 
prevents is a check-in by anybody but the locker. 


If your RCS file is private— if you are the only person who is going to deposit revisions into it— strict locking isnot needed 
and you can turn it off. If strict locking is turned off, the owner of the RCS file need not havea lock for checkin; all others 
sill do. Turning strict locking off and on isdone with the commands res -u f.c andrcs -L f.c. If you don’t want to 
clutter your working directory with RCS files, create a subdirectory called acs in your working directory, and move all your 
RCS filesthere rcs commands will look first into that directory to find needed files. All the commands discussed here will 
still work, without any modification. (Actually, pairs of RCS and working files can be specified in three ways: both are given, 
only the working file is given, or only the RCS fileis given. Both RCS and working files may have arbitrary path prefixes; rcs 
commands pair them up intdligently.) 


To avoid the deletion of the working file during checkin (in case you want to continue editing or compiling), invoke 

ci -1 f.c or ci -u f.c 

These commands check in f.c as usual, but perform an implicit checkout. The first form also locks the checked in revision, 
the second one doesn't. T hus, these options save you one checkout operation. The first form is useful if you want to 


continue editing, the second one if you just want to read the file Both update the identification markersin your working 
file. (See the following subsection, “Automatic | dentification.”) 


You can giveci thenumber you want assigned to a checked in revision. Assume all your revisions were numbered 1.1, 1.2, 
1,3, e&c., and you would like to start release 2. The command: 


ci -r2 f.c or ci -r2.1 f.c 


assigns the number 2.1 to the new revision. From then on, ci will number the subsequent revisions with 2.2, 2.3, and so on. 
The corresponding co commands: 


resmerge 


co -r2 f.c 


and 
co -r2.1 f.c 
retrieve the latest revision numbered 2.x and the revision 2.1, respectively. co without a revision number selects the latest 


revision on the trunk, that is, the highest revision with anumber consisting of two fields. Numbers with more than two 
fidds are needed for branches. For example, to start a branch at revision 1.3, invoke 


ci -r1.3.1 f.c 
This command starts a branch numbered 1 at revision 1.3, and assigns the number 1.3.1.1 to the new revision. For more 
information about branches, see resfile(5). 

AUTOMATIC IDENTIFICATION 


RCS can put special strings for identification into your source and object code To obtain such identification, place the 
marker: 


$Id$ 

into your text, for instance inside a comment. RCS will replace this marker with a string of the form: 

$Id: filename revision date time author state $ 

With such a marker on the first page of each module you can always see with which revision you are working. RCS keeps 


the markers up-to-date automatically. To propagate the markers into your object code, simply put them into literal character 
strings. In C, this is doneas follows: 


static char rcsid[] = "$Id$"; 
Thecommand ident extracts such markers from any file even object code and dumps. Thus, ident lets you find out which 
revisions of which modules were used in a given program. 


You may also find it useful to put the marker sLog$ into your text, inside a comment. This marker accumulates the log 
messages that are requested during checkin. T hus, you can maintain the complete history of your file directly inside it. T here 
are several additional identification markers, see co(1) for details. 


IDENTIFICATION 


Author: Walter F. Tichy. 

M anual Page Revision: 5.3; Release D ate: 1993/11/03. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993 Paul Eggat. 


SEE ALSO 


ci(1), co(1), ident(1), res(1), resdift(1), resintro(1), resmerge(1), r1og(1) 





“RCS—A System for Version Control” by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 


GNU, 3 November 1993 


resmerge 


resmerge— M ergeRCS revisions 


SYNOPSIS 


rcsmerge [options] file 


Part |: User Commands 


DESCRIPTION 
resmerge incorporates the changes between two revisions of an RCS fileinto the corresponding working file. 
Pathnames matching an rcs suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(1). 


At least one revision must be specified with one of the options described in the next subsection, usually -r. At most two 
revisions may be specified. If only one revision is specified, the latest revision on the default branch (normally the highest 
branch on the trunk) is assumed for the second revision. Revisions may be specified numerically or symbolically. 


resmerge prints a warning if there are overlaps, and ddimits the overlapping regions as explained in merge(1). The command 
is useful for incorporating changes into a checked-out revision. 


OPTIONS 

-A Output conflicts using the -a style of ditr3(1), if supported by ditt3. T his merges all changes leading 
from file2 to file3 into file1, and generates the most verbose output. 

-E, -e T hese options specify conflict styles that generate less information than -a. See aiff3(1) for details. The 
default is-e. With-e, rcsmerge does not warn about conflicts. 

-ksubst Usesubst -style keyword substitution. See co(1) for details. For example -kk -r1.1 -r1.2 ignores 
differences in keyword values when merging the changes from 1.1 to 1.2. It normally does not make sense 
to merge binary files as if they were text, so rcsmerge refuses to merge files if -kb expansion isused. 

-p[rev] Send the result to standard output instead of overwriting the working file 

-q[rev] Run quietly; do not print diagnostics. 

-r[rev] M erge with respect to revision rev. H erean emptyrev stands for the latest revision on the default branch, 
normally the head. 

-T This option has no effect; it is present for compatibility with other res commands. 

-V Print RCS's version numbe.. 

-Vn Emulate RCS version n. See co(1) for details. 

-xsuffixes Usesuffixes to characterize RCS files. See ci(1) for details. 

-zz0ne Usezone asthe timezone for keyword substitution. See co(1) for details. 

EXAMPLES 


Suppose you have rdeased revision 2.8 of t.c. Assume, furthermore, that after you complete an unrdeased revision 3.4, you 
receive updates to release 2.8 from someone else. To combine the updates to 2.8 and your changes between 2.8 and 3.4, put 
the updates to 2.8 into file .c and execute 


resmerge -p -r2.8 -r3.4 f.c >f.merged.c 


Then examine f.merged.c. Alternatively, if you want to save the updates to 2.8 in theRCS file, check then in asrevision 
2.8.1.1 and execute co -j: 


ci -r2.8.1.1 f.c 
co -r3.4 -j2.8:2.8.1.1 f.c 


As another example, the following command undoes the changes between revision 2.4 and 2.8 in your currently checked out 
revision in f.c: 


resmerge -r2.8 -r2.4 f.c 
N ote the order of the arguments, and that ¢.c will be overwritten. 


ENVIRONMENT 


RCSINIT Options prepended to the argument list, separated by spaces. See ci(1) for details. 


DIAGNOSTICS 


Exit status is@ for no overlaps, 1 for some overlaps, 2 for trouble. 
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IDENTIFICATION 
Author: Walter F. Tichy. 
M anual Page Revision: 5.6; Release D ate: 1995/06/01. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 
SEE ALSO 
ci(1), co(1), ident(1), merge(1), rcs(1), resditt(1), resintro(1), rlog(1), resfile(5) 


“RCS—A System for Version Control” by Walter F. Tichy, software-Practice & Experience 15, 7 (July 1985), pages 
637-654. 


GNU, 1 June1995 


rdist 





rdist— Remote file distribution program 
SYNOPSIS 
rdist [-nqbRhivwy] [-f distfile] [-d var=value] [-m host] [name ...] 
rdist [-nqbRhivwy] -c name ... [login@host:dest] 
DESCRIPTION 
rdist isa program to maintain identical copies of files over multiple hosts. It preserves the owner’, group, mode, and mtime 


of files if possible and can update programs that are executing. rdist reads commands from distfile to direct the updating 
of files and/or directories. 
O ptions specific to the first synopsis form: 


- If distfile is -, the standard input is used. 
-f distfile Use the specified distfile. 


If either the -f or - option is not specified, the program looks first for distfile, then Distfile to useas the input. If no 
names are specified on the command line rdist will update all of thefiles and directories listed in distfile. O therwise, the 
argument is taken to be the name of afile to be updated or the label of acommand to execute. If label and filenames conflict, 
it isassumed to be alabel. T hese may be used together to update specific files using specific commands. 
Options specific to the second synopsis form: 
-C Forces rdist to interpret the remaining arguments as a small distfile. 

The equivalent distfile is as follows: 

name ... -& login@ host install dest ; 


Options common to both forms: 
-b Binary comparison. Perform a binary comparison and update files if they differ rather than comparing 
dates and sizes. 


-d var=value Definevar to haveval ue. The -a option is used to define or override variable definitions in the distfile. 
value Can be the empty string, onename, or alist of names surrounded by parentheses and separated by 


tabs and/or spaces. 

-h Follow symbolic links. C opy the file that the link points to rather than the link itsdf. 

-i Ignore unresolved links. rdist will normally try to maintain the link structure of files being transferred and 
warn the user if all the links cannot be found. 

-m host Limit which machines are to be updated. M ultiple -m arguments can be given to limit updates to a subset 


of the hosts listed in the distfile. 
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-n Print the commands without executing them. T his option is useful for debugging distfile. 

-q Quiet mode Filesthat are bang modified are normally printed on standard output. T he -q option 
suppresses this. 

-R Remove extraneous files. If a directory is being updated, any files that exist on the remote host that do not 
exist in the master directory are removed. This is useful for maintaining truly identical copies of directo- 
ries. 

“V Verify that the files are up-to-date on all the hosts. Any files that are out-of-date will be displayed, but no 
files will be changed nor any mail sent. 

-W W hole mode The whole filenameis appended to the destination directory name. N ormally, only the last 


component of aname is used when renaming files. T his will preserve the directory structure of the files 
being copied instead of flattening the directory structure For example, renaming alist of files such as 
dirt/f1 dir2/f2 to dir3 would create files dir3/dir1/f1 and dir3/dir2/f2 instead of dir3/f1 and dir3/f2. 

“y Younger mode. Files are normally updated if their mtime and size (see stat(2)for more details) disagree. 
The -y option causes rdist not to update files that are younger than the master copy. This can be used to 
prevent newer copies on other hosts from being replaced. A warning message is printed for files that are 
newer than the master copy. 


distfile contains a sequence of entries that specify the files to be copied, the destination hosts, and what operations to 
perform to do the updating. Each entry has one of the following formats: 
<variable name>'=' <name list> 


[label:]<source list> '->' <destination list><command list> 
[label:]<source list> '::' <time_stamp file><command list> 


The first format is used for defining variables. The second format is used for distributing files to other hosts. T he third 
format is used for making lists of files that have been changed since some given date. The source list specifies a list of files 
and/or directories on the local host that are to be used as the master copy for distribution. T he destination list isthe list of 
hosts to which thesefiles are to be copied. Each file in the source list is added to alist of changes if the file is out-of-date on 
the host that is being updated (second format), or the file is newer than the timestamp file (third format). 


Labels are optiond. T hey are used to identify a command for partial updates. 


N ewlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with # and end with a 
newline 


Variables to be expanded begin with $ followed by one character or aname enclosed in curly braces (see the examples at the 
end). 


The source and destination lists have the following format: <name> or '(' <zero or more names separated by white-space> 
ne 

The shal meta characters [, }, {, }, *, and ? are recognized and expanded (on the local host only) in the same way aS csh(1). 
They can be escaped with a backslash. The ~ character is also expanded in the same way as csh(1) but is expanded separately 
on the local and destination hosts. W hen the -w option is used with a filename that begins with ~, everything exceot the 
home directory is appended to the destination name. Filenames that do not begin with / or ~ use the destination user’shome 
directory as the root directory for the rest of the filename. 

The command list consists of zero or more commands of the following format: 

‘install' <options> opt_dest_name ';' 

‘notify’ <name list> ';' 

‘except’ <name list> ';' 

‘except_pat' <pattern list> ';' 

‘special' <name list> string ';' 


The install command is used to copy out-of-date files and/or directories. Each source file is copied to each host in the 
destination list. Directories are recursively copied in the same way. opt_dest_name iS an optional parameter to rename files. If 
nO install Command appears in the command list or the destination nameis not specified, the source filename is used. 
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Directories in the pathname will be created if they do not exist on the ranote host. To help prevent disasters, a nonempty 
directory on a target host will never be replaced with a regular file or a symbolic link. H owever, under the -r option, a 
nonempty directory will be removed if the corresponding filename is completely absent on the master host. T he options are 
-R, -h, -i, -v, -w, -y, and -b and have the same semantics as options on the command line except they only apply to the files 
in the source list. The login name used on the destination host isthe same as the local host unless the destination name is of 
the format 1ogin@host. 


The notify command is used to mail the list of files updated (and any errors that may have occurred) to the listed names. If 
no @ appearsin the name the destination host is appended to the name (for example namei@host, name2@host). 





The except command is used to update all of the files in the source list except for the files listed in name list . This is usually 
used to copy everything in a directory except certain files. 


The except_pat command is like the except command except that pattern list isalist of regular expressions (see ed(1) for 
details). If one of the patterns matches some string within a filename that file will be ignored. N ote that because \ is a quote 
character, it must be doubled to become part of the regular expression. Variables are expanded in pattern list, but not shal 
file pattern- matching characters. To include as, it must be escaped with \. 


The special command is used to specify sh(1) commands that are to be executed on the remote host after the file in name 
list is updated or installed. If the name list is omitted, then the shell commands will be executed for every file updated or 
installed. The shell variable FILE is set to the current filename before executing the commands in string . string starts and 
ends with double quotes (") and can cross multiple linesin distfile . Multiple commands to the shal should be separated by 
a semicolon. Commands are executed in the user’s home directory on the host being updated. T he special command can be 
used to reduild private databases, and so on after a program has been updated. 


The following isa small example 

HOSTS = ( matisse root@arpa ) 

FILES = ( /bin /lib /usr/bin /usr/games 
/usr/include/{*.h,{stand, sys, vax* ,pascal,machine}/*.h 
/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) 


EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrce sendmail.cf 
sendmail.fc sendmail.hf sendmail.st uucp vfont ) 


${FILES} -> ${HOSTS} install -R ; except /usr/lib/${EXLIB} ; except /usr/games/lib ; 
special /usr/lib/sendmail "/usr/lib/sendmail -bz" ; 


sres: /usr/src/bin -> arpa except pat ( \\.o\$ /SCCS\$); 
IMAGEN = (ips dviimp catdvi) 
imagen: /usr/local/${IMAGEN} -> arpa install /usr/local/lib ; notify ralph ; 


${FILES} :: stamp.cory notify root@cory ; 


FILES 
distfile Input command file 
/tmp/rdist* Temporary file for update lists 
SEE ALSO 
sh(1), csh(1), stat(2) 
HISTORY 


The rdist command appeared in BSD 4.3. 
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DIAGNOSTICS 


A complaint about mismatch of rdist version numbers may really stem from some problem with starting your shall; for 
example, you arein too many groups. 


BUGS 
Source files must reside on the local host where rdist is executed. 
There is no easy way to havea special command executed after all filesin a directory have been updated. 
Variable expansion only works for name lists; there should be a general macro facility. 
rdist aborts on files that have a negative mtime (before an 1, 1970). 


There should bea force option to allow replacenent of nonempty directories by regular files or symlinks. A means of 
updating file modes and owners of otherwise identical files is also needed. 


BSD 4.3, 30 Decanbe 1993 
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reconfig— Convert old X config to new XF86C onfig 
SYNOPSIS 


reconfig < Xconfig > XF86Config 


DESCRIPTION 


Thereconfig program converts the X config file format used in XFree86 versions prior to 3.1 into the XF86C onfig format 
currently used. The XF86C onfig format contains more information than the Xconfig format, so manual editing is required 
after converting. 


SEE ALSO 


xFree86(1), xF86Config(4/5), xf8écontig(1) 


AUTHOR 


Gertjan Akkerman 


BUGS 


Comment lines are stripped out when converting. 
XFree86 Vergon 3.1.1 


ref 


ret 

ref— Display aC function header 
SYNOPSIS 

ref [-t] [-x] [-c class]... [-f file]... tag 
DESCRIPTION 


ref quickly locates and displays the header of a function. T o do this, ret looksin the tags file for the line that describes the 
function, and then scans the source file for the function. W hen it locates the function, it displays an introductory comment 
(if there is one), the function’s declaration, and the declarations of all arguments. 


SEARCH METHOD 


ref uses a fairly sophisticated tag look-up algorithm. If you supply a filename via -f file, then elvis first scans the tags 
file for a static tag from that file This search is limited to the tags file in the current directory. 


If you supply aclass name via -c class, then elvis searches for a tag from that class. T his search is not limited to the 
current directory; You can supply alist of directoriesin the environment variable TAGPATH, and ref will search through the 
tags filein each directory until it finds a tag in the desired class. 


If that fails, ret will then try to look up an ordinary global tag. This search checks all of the directories listed in TAGPATH, too. 
If the tag being sought doesn’t contain any colons, and you haven't given a -x flag, then any static tagsin atags file will be 
treated as global tags. 

If you've given the -t flag, then re will simply output the tag line that it found, and then exit. Without -+, though, ref 
will search for the tag line It will try to open the source file, which should bein the same directory as the tags file where the 
tag was discovered. If the source file doesn’t exist, or is unreadable, then ref will try to open a file called refs in that 
directory. Either way, ref will try to locate the tag, and display whatever it finds. 


INTERACTION WITH elvis 
ref iS used by the elvis shift -k command. If the cursor islocated on aword such as splat, in thefile foo.c, then elvis will 
invoke ref with the command ret -f foo.c splat. 
If elvis has been compiled with the -pEXTERNAL_TAGS flag, then elvis will use ref to scan the tags files. This is slower than 
the built-in tag searching, but it allows elvis to access the more sophisticated tag lookup provided by ref. O ther than that, 
external tags should act exactly like internal tags. 


OPTIONS 
-t Output tag info, instead of the function header. 
-f file The tag might be a static function in file. You can use several -f flags to have ref consider static tags 
from more than one file 
-c class The tag might be amember of class class. You can use several -c flags to have ref consider tags from 
more than oneclass. 
FILES 
tags List of function names and thar locations, generated by ctags 
refs Function headers extracted from source files (optional) 
ENVIRONMENT 
TAGPATH List of directories to be searched. The elements in the list are separated by ather semicolons (for MS-DOS, 


Atari TOS, and AmigaD os), or by colons (every other operating system). For each operating system, ref 
has a built-in default which is probably adequate. 
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NOTES 


You might want to generate a tags file for the directory that contains the source code for standard C library on your system. 
If licensing restrictions prevent you from making the library source readable by everybody, then you can have ctags generate 
arefs file, and make refs readable by everybody. 


If your system doesn’t come with the library source code, then perhaps you can produce something workable from the 1int 
libraries. 


SEE ALSO 


elvis(1), ctags(1) 


AUTHOR 


Steve Kirkendall (kirkenda@cs.pdx. edu) 


reset 


reset— Reset the taminal 


SYNOPSIS 


clear 


DESCRIPTION 


reset CallS tput(1) with the clear, rmacs, rmm, rmul, rs1, rs2, and rs3 arguments. T his causes tput to send appropriate 
reset strings to the terminal based on information in /etc/termcap (for theGNU or BSD tput) orin the terminfo database 
(for the ncurses tput). T his sequence seems to be sufficient to reset the Linux VC’s when they start printing “funny- 
looking” characters. For good measure, stty(1) is called with the sane argument in an attempt to get Cooked mode back. 


SEE ALSO 


reset(1), stty(1), tput(1) 


AUTHOR 
Rik Faith (faithe@cs.unc. edu) 
Linux 0.99, 10 October 1993 


resize 


resize— Set TERMcaP and terminal settings to current xterm window size 


SYNOPSIS 
resize [ -u | -c ][-s [ row col ]] 
DESCRIPTION 


resize prints a shell command for setting the TERM and TERMcAP environment variables to indicate the current size of xterm 
window from which the command is run. For this output to take effect, resize must either be evaluated as part of the 
command line (usually done with a shell alias or function) or else redirected to a file that can then be read in. From theC 
shell (usually known as /bin/csh), thefollowing alias could be defined in the user's .cshre: 


% alias rs 'set noglob; eval 'resize'' 


After resizing the window, the user would type: 


Sor 


rgo3toppm 457 


Users of versions of the Bourne sha! (usually known as /bin/sh) that don’t have command functions will need to send the 
output to atemporary file and the read it back in with the . command: 


$ resize > /tmp/out 


$ . /tmp/out 
OPTIONS 

The following options may be used with resize: 

-u This option indicates that Bourne shell commands should be generated even if the user’s current 
shell isn’t /bin/sh. 

-c This option indicates that C shell commands should be generated even if the user’s current shell 
isn’t /bin/csh. 

-s [rows columns] This option indicates that Sun console escape sequences will be used instead of the special xterm 


escape code If rows andcolumns are given, resize will ask the xterm to resize itself. H oweve,, the 
window manager may choose to disallow the change 


FILES 
/etc/termcap Forthebase termcap etry to modify 
“/.cshre User's alias for the command 

SEE ALSO 
csh(1), tset(1), xterm(1) 

AUTHORS 


M ark Vandevoorde (M IT -Athena), Edward M oy(Berkeley) 
Copyright© 1984, 1985 by XConsortium 
See X(1) for acomplete copyright notice. 


BUGS 
The -u or -c must appear to the left of -s if both are specified. 
X Verson 11 Release 6 


rev 


rev— Reverse lines of afile 


SYNOPSIS 


rev [file] 


DESCRIPTION 


The rev utility copies the specified files to the standard output, reversing the order of characters in every line If no files are 
specified, the standard input is read. 


21 March 1992 


rgb3toppm 


rgb3toppm— C ombine three portable graymaps into one portable pixmap 
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SYNOPSIS 


rgb3toppmredpgmfile greenpgmfile bluepgmfile 


DESCRIPTION 


rgb3toppm reads three portable graymaps as input and combines them and produces one portable pixmap as output. 


SEE ALSO 


ppmtorgb3(1), pgmtoppm(1), ppmtopgm(1), ppm(5), pgm(5) 


AUTHOR 
Copyright© 1991 by J ef Poskanzer. 
15 February 1990 
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rlog— Print log messages and other information about RCS files 


SYNOPSIS 


rlog [ options ] file ... 


DESCRIPTION 
rlog prints information about RCS files. 
Pathnames matching an rcs suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(1). 


rlog prints the following information for each RCS file. RCS pathname working pathname, head (the number of the latest 
revision on thetrunk), default branch, access list, locks, symbolic names, suffix, total number of revisions, number of 
revisions selected for printing, and descriptive text. Thisis followed by entries for the selected revisionsin reverse chronologi- 
cal order for each branch. For each revision, rlog prints revision number, author, date/time state, number of lines added/ 
deleted (with respect to the previous revision), locker of the revision (if any), and log message. All times are displayed in 
Coordinated Universal Time (UTC) by default; thiscan be overridden with -z. Without options, riog prints complete 
information. T he options below restrict this output. 


“L Ignore RCS files that have no locks set. Thisis convenient in combination with -h, -1, and -r. 

-R Print only thenameof thercs file. T hisis convenient for translating a working pathname into an RCS 
pathname. 

-h Print only theRCS pathname, working pathname, head, default branch, access list, locks, symbolic names, 
and suffix. 

-t Print the sameas -h, plusthe descriptive text. 

-N Do not print the symbolic names. 

-b Print information about the revisions on the default branch, normally the highest branch on the trunk. 

-ddates Print information about revisions with a checkin date/time in the ranges given by the semicolon-separated 





list of dates. A range of the form di<a2 or d2>d1 selects the revisions that were deposited between a1 and 
d2 exclusive. A range of the form <a or a> selects all revisions earlier than a. A range of the form a< or >d 
selects all revisions dated later than a. If < or > is followed by =, then the ranges are inclusive, not exclusive 
A range of the form a sdects the single, latest revision dated a or earlier. The date/time strings a, d1, and 
d2 are in the free format explained in co(1). Quoting is normally necessary, especially for < and >. N ote 
that the separator is a semicolon. 

-l[lockers] Print information about locked revisions only. In addition, if the comma-separated list! ockers of login 
names is given, ignore all locks other than thosehdd by the! ockers. For example, rlog -L -R -lwft 
Rcs/* prints the name of RCS files locked by the user wft. 


-r[revisions] Print information about revisions given in the comma-separated list revisions of revisions and ranges. A 
range rev1: rev2 meansrevisions revi to rev2 on the same branch, :rev means revisions from the 
beginning of the branch up to and including rev, and rev: means revisions starting with rev to the end of 
the branch containing rev. An argument that is a branch means all revisions on that branch. A range of 
branches means all revisions on the branches in that range A branch followed by a. means the latest 
revision in that branch. A bare -r with no revisions means the latest revision on the default branch, 
normally the trunk. 


-sstates Print information about revisions whose state attributes match one of the states given in the comma 
separated list st ates. 

-w[logins] Print information about revisions checked in by users with login names appearing in the comma-separated 
lit logins. If logins is omitted, the user’s login is assumed. 

-T This option has no effect; it is present for compatibility with other res commands. 

-V Print the RCS version number. 

-Vn Emulate RCS version n when generating logs. (See co(1) for more details.) 

-xsuffixes Usesuffixes to characterizeRCS files. (See ci(1) for details.) 


rlog prints the intersection of the revisions selected with the options -a, -1, -s, and -w, intersected with the union of the 
revisions sdected by -b and -r. 


-zz0ne Specifies the date output format, and specifies the default time zone for date in the -ddates option. The 
zone Should be empty, anumeric UTC offset, or the special string Lt for local time. T he default isan 
empty zone, which usesthe traditional RCS format of UTC without any timezone indication and with 
slashes separating the parts of the date otherwise, times are output in so 8601 format with time zone 
indication. For example if local timeisJ anuary 11, 1990, 8 p.m. Pacific Standard Time, eight hours west 
of UTC, then the time is output as follows: 


option time output 


-Z 1990/01/12 04:00:00 (default) 
-zLT 1990-01-11 20:00:00-08 
-2+05:30 1990-01-12 09:30:00+05:30 


EXAMPLES 
H ere are four r1og commands: 
rlog -L -R RCS/* 
rlog -L -h RCS/* 
rlog -L -1 RCS/* 
rlog RCS/* 


The first command prints the names of all RCS files in the subdirectory rcs that have locks. The second command prints 
the headers of those files, and the third prints the headers plus the log messages of the locked revisions. T he last command 
prints complete information. 


ENVIRONMENT 
RCSINIT Options prepended to the argument list, separated by spaces. (See ci(1) for details.) 


DIAGNOSTICS 


The exit status is zero if and only if all operations were successful. 
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IDENTIFICATION 
Author: Walter F. Tichy 
M anual Page Revision: 5.9; Release D ate: 1995/06/16 
Copyright© 1982, 1988, 1989 W alter F. Tichy 
Copyright© 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert 
SEE ALSO 
ci(l), co(1), ident(1), res(1), resdift(1), resintro(1), resmerge(1), resfile(5) 
“RCS-A System for Version Control” by W alter F. Tichy, SoftwarePractice & Experience 15, 7 (July 1985), pages 637-654. 


BUGS 


The separator for revision ranges in the -r option used to be - instead of :, but this leads to confusion when symbolic names 
contain -. For backwards compatibility, r1og -r still supports the old - separator, but it warns about this obsolete use. 


GNU, 16 June1995 


rlogin 

rlogin— Remote login 
SYNOPSIS 

rlogin [-8EKLdx] [-e char] [-k realm] [-1 username] host 
DESCRIPTION 


rlogin starts a terminal session on aremote host host. 


rlogin first attempts to use the K erberos authorization mechanism, described in the following subsection. If the remote host 
does not support K erberos, the standard Berkeley authorization mechanism is used. T he options are as follows: 








-8 The -8 option allows an dight-bit input data path at all times; otherwise, parity bits are stripped except when the 
remote side's stop and start characters are other than *s/*a. 

-E The -E option stops any character from being recognized as an escape character. W hen used with the -8 option, 
this provides a completdy transparent connection. 

-K The -k option turns off all K erberos authentication. 

“L The -L option allows the riogin session to berun in 1itout mode (See tty(4) for details). 

-d The -d option turnson socket debugging (see the setsockopt(2) man page) on the tcp sockets used for 
communication with the remote host. 

-e The -e option allows user specification of the escape character, which is the tilde (~) by default. This specification 
may be as a literal character, or as an octal value in the form nnnn. 

-k The -k option requests rlogin to obtain tickets for the remote host in realm realm instead of the remote host's 
realm as determined by krb_realmofhost(3). 

=x The -x option turns on DES encryption for all data passed via the rlogin session. This may impact response time 


and CPU utilization, but provides increased security. 


A lineof the form <escape char> disconnects from the remote host. Similarly, the line<escape char>*z will suspend the 
rlogin session, and <escape char><delayed-suspend char> suspends the send portion of therr1ogin, but allows output 
from the renote system. By default, the tilde (~) character isthe escape character, and normally control -y (*y) isthe 
dedayed-suspend character. 


All echoing takes place at the remote site, so that (except for ddays) the rlogin is transparent. Flow control via *s/*a and 
flushing of input and output on interrupts is handled properly. 


: 
KERBERO S AUTHENTICATION 


Each user may have a private authorization list in the filein hisor her home directory. Each line in this file should contain a 
Kerberos principal name of the form principal.instance (@realm). If the originating user is authenticated to one of the 
principals named, access is granted to the account. The principal accountname.(@localrealm) is granted access if there is 
no file. O therwise, alogin and password will be prompted for on the remote machine as in 1ogin(1). To avoid certain 
security problems, the file must be owned by the renote user. 


If K erberos authentication fails, a warning message is printed and the standard Berkeley riogin is used instead. 


ENVIRONMENT 


The following environment variable is utilized by riogin: 


TERM D etermines the user’s terminal type 
SEE ALSO 

rsh(1), kerberos(3), krb_sendauth(3), krb_realmofhost(3) 
HISTORY 

The rlogin command appeared in BSD 4.2. 
BUGS 


rlogin will be replaced by te1net(1) in the near future 
M oreof the environment should be propagated. 
BSD 4.2, 27 July1991 


rm 


rm— Remove files 


SYNOPSIS 
rm [-dfirvR] [--directory] [--force] [--interactive] [--recursive] 
[--help] [--version] [--verbose] name... 

DESCRIPTION 


This manual page documents the anu version of rm. rm renoves each specified file. By default, it does not renove directories. 
If afileis unwritable, the standard input isa tty, and the -f or --force option is not given, rm prompts the user for whether 
to remove the file If the response does not begin with y or y, the file is skipped. 


GNU rm, like every program that uses the getopt function to parse its arguments, lets you use the - - option to indicate that 
all following arguments are nonoptions. To remove afile called -f in the current directory, you could type ather 


rm -- -f 
or 
rm ./-f 


TheUNIX rm program’s use of asingle - for this purpose predates the devdopment of the getopt standard syntax. 


OPTIONS 


-d, --directory Remove directories with unlink instead of rmdir, and don’t require a directory to be empty before 
trying to unlink it. O nly works for the superuser. Because unlinking a directory causes any files in 
the ddeted directory to become unreferenced, it is wise to fsck the filesystem after doing this. 
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-f, --force Ignore nonexistent files and never prompt the user. 

-i, --interactive Prompt whether to removeeach file. If the response does not begin with y or y, the file is skipped. 
-r, -R, --recursive Remove the contents of directories recursivd y. 

-v, -- verbose Print the name of each file before removing it. 

--help Print a usage message on standard output and exit successfully. 

--version Print version information on standard output, then exit successfully. 


GNU FileUtilitie 


rmdir 


rmdir— Remove enpty directories 


SYNOPSIS 


rmdir [-p] [--parents] [--help] [--version] dir... 


DESCRIPTION 


This manual page documents the GN U version of rmdir. rmdir removes each given enpty directory. If any nonoption 
argument does not refer to an existing enpty directory, it is an error. 


OPTIONS 
-p, --parents Remove any parent directories that are explicitly mentioned in an argument, if they become enpty 
after the argument file is renoved. 
--help Print a usage message on standard output and exit successfully. 
--version Print version information on standard output, then exit successfully. 
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rmmod— U nload loadable modules 


SYNOPSIS 


rmmod [ -r ] module ... 


DESCRIPTION 
rmmod unloads loadable modules from thekernel. 


rmmod tries to unload a set of modules from the kernal, with the restriction that they are not in use and that they are not 
referred to by other modules. 


If more than onemodule is named on the command line, themodules will be removed in the given orde.. T his supports 
unloading of stacked modules. 


With the option -r, a recursive removal of modules will be attempted. This means that if a top module in a stack is named 
on the command line, all modules that are used by this module will be renoved as well, if possible. 


SEE ALSO 


insmod(1), 1smod(1), ksyms(1), modules(2) 


rnews 
HISTORY 


The module support was first conceived by Anonymous (as far as! Know... ). Linux version by Bas Laarhoven 
(bas@vimec.n1), 0.99.14 version by Jon Tombs (jon@gtex@2.us.es), extended by Bjorn Ekwall (bjarn@blox.se). 


BUGS 
rmmod might have some, but they are wd hidden. 
Linux, 14 May 1995 


rnews 

rnews— Receive news from a UUCP connection 
SYNOPSIS 

rnews [ -h host J[-v ][-U ][-S master ][input ] 
DESCRIPTION 


rnews reads messages sent by a downstream uucp newsfeed and sends them to the local InterN etN ews server. T he message is 
read from the specified input file, or standard input if no input is named. 


If the -s flag is used, then rnews will connect to the specified host. If the flag is not used, it will try to connect to the server 
by opening aUN1IX-domain stream connection. If that fails, it will try to open aT CP connection to the default remote 
server. 


If the server is not available the message is spooled into a new file created in the /var/spool1/rnews directory. The -u flag 
may be used to send all spooled messages to the server when it becomes available again, and can be invoked regularly by 
cron(8). 


When sent over uucp, U set articles are typically joined in a single batch to reduce the uucp overhead. Batches can also be 
compressed, to reduce the communication time. If a message does not start with anumber sign (#) and an exclamation 

point, then the entire input is taken as a single news article. If it does start with those two characters, then the first line is read 
and interpreted as a batch command. 


If thecommand is #! rnews non, wherennn isanumber, then the next nnn bytes (starting with the next line) are read asa 
news article. 


If the command is#! cunbatch, then the rest of input is fed to the compress(1) program with the -d flag to uncompress it, 
and the output of this pipe is read as input from rnews. This is for historical compatibility— there isno program named 
cunbatch. A compressed batch will start with a #! cunbatch line, then contain a series of articles separated by #! rnews nnn 
lines. 


If the command is any other word, then rnews will try to execute a program with that name in the directory /news/bin/ 
rnews. T he batch will be fed into the program’s standard input, and the standard output will beread back as input into 
rnews. 


If rnews detects any problems with an article, such as a missing header or an unintelligible reply from the server, it will savea 
copy of thearticlein the /var/spool/rnews/bad directory. If the -v flag is used, it will print a notice of all such errors on the 
standard error, naming the input file (if known) and printing the first few characters of the input. Errors are always logged 
through syslog(3). 

If the -h flag is given, or failing that, the environment variable uu_MACHINE isset, then rnews will log the M essage ID and 
host for each article offered to the server via syslog(3). Logging will only be done if the value is not an empty string. 


BUGS 


rnews Cannot process articles that have enbedded \asin them. 
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HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN &tN ews. 


SEE ALSO 
inna(8). 


rpcgen 


rpegen— An RPC protocol compiler 


SYNOPSIS 
rpcgen infile 
rpcgen [-D name[= value]] [-T] [-K secs] infile 


rpcgen -cj-hj-l}-m}-t [-o outfile] infile 
rpcgen [-I] -s nettype [-o outfile] infile 
rpcgen -n netid [-o outfile] infile 


DESCRIPTION 


rpegen isa tool that generates C codeto implement an RPC protocol. Theinput to rpcgen is alanguage similar to C known 
as RPC language (Remote Procedure C all Language). rpcgen is normally used asin the first synopsis where it takes an input 
file and generates up to four output files. If the infile isnamed proto.x, then rpcgen will generate a header filein proto.h, 
xdr routinesin proto_xdr.c, server-side stubs in proto_svc.c, and Client-side stubs in proto_cint.c. 


With the -t option, it will also generatethe RPC dispatch table in proto_tb1.i. With the -sc option, it will also generate 
sample code that would illustrate how to use the renote procedures on the client side T his code would be created in 
proto_client.c. With the -Ss option, it will also generate a sample server code that would illustrate how to write the 
remote procedures. T his code would be created in proto_server.c. T he server created can be started both by the port 
monitors (for example, inetd or listen) or by itself. W hen it is started by a port monitor, it creates servers only for the 
transport for which the file descriptor @ was passed. The name of the transport must be specified by setting up the environ- 
mental variable pu_TRANSPORT. 


W hen the server generated by rpcgen is executed, it creates server handles for all the transports specified in NETPATH 
environment variable, or if it is unset, it creates server handles for all the visible transports from /etc/netconfig file N ote: 
the transports are chosen at runtime and not at compile time. When the server is sef-started, it backgrounds itself by default. 
A special define symbol rPc_svc_Fe can be used to run the server process in the foreground. T he second synopsis provides 
special features that allow for the creation of more sophisticated RPC servers. T hese features include support for user- 
provided #defines and RPC dispatch tables. The entries in the RPC dispatch table contain 


m Pointers to the service routine corresponding to that procedure 
m A pointer to the input and output arguments 
m= Thesize of these routines 


A server can use the dispatch table to check authorization and then to execute the service routine; a client library may use it 
to deal with the details of storage management and xadr data conversion. T he other three synopses shown in the preceding 
paragraph are used when one does not want to generate all the output files, but only a particular one (Some examples of 
their usage is described in the “Example” subsection.) W hen rpcgen is executed with the -s option, it creates servers for that 
particular class of transports. W hen executed with the -n option, it creates a server for the transport specified by netia. If 
infile isnot specified, rpcgen accepts the standard input. TheC preprocessor, cc -& (See cc(1) for details), isrun on the 
input file before it is actually interpreted by rpcgen. For each type of output file, rpcgen defines a special preprocessor 
symbol for use by the rpcgen programmer, as follows: 





RPC_HDR Defined when compiling into header files 

RPC_XDR Defined when compiling into XD R routines 

RPC_SVC Defined when compiling into server-side stubs 

RPC_CLNT Defined when compiling into client-side stubs 

RPC_TBL Defined when compiling into arc dispatch tables Any line beginning with % is passed directly into the 


output file, uninterpreted by rpcgen. For every data type referred to in infile, rpcgen assumes that there 
exists a routine with the string xar prepended to the name of the data type If this routine does not exist in 
the RPC/XDR library, it must be provided. Providing an undefined data type allows customization of 

XDR routines. The following options are available 

- Generate all the files including sample code for client and server side. 

-b This generates code for the SunO S4.1 style of rpc. It is for backwards compatibility. 


This is the default. 

“5 This generates code for the SysVr4 style of rpc. It is used by the Transport 
Independent RPC that isin Svr4 systems. By default, rpcgen generates code for 
SunO S4.1 type of rpc. 

“Cc Compile into XDR routines. 

-C Generate codein ANSI C. This option also generates code that could be compiled 
with the C ++ compile. T hisis the default. 

-k Generate codein K&R C. Thedefault is ANSI C. 

-Dname[ =val ue] Define asymbol name. Equivalent to the #define directivein the source If no val ue 
iS given, val ue iS defined as 1. T his option may be specified more than once. 

-h Compile into C data-definitions (a header file). -t option can be used in conjunc- 
tion to produce a header file that supports RPC dispatch tables. 

“I Generate a service that can be started from inetd. The default is to generate a static 
service that handles transports selected with -s. Using -1 allows starting a service by 
either method. 

-K secs By default, services created using rpcgen wait 120 seconds after servicing a request 


before exiting. T hat interval can be changed using the -x flag. T 0 create a server that 
exits immediately upon servicing arequest, -k @ can be used. To create a server that 
never exits, the appropriate argument is -k -1. 

When monitoring for aserver, some port monitors, such aS 1isten(1M ), always 
spawn anew process in response to a service request. If it is known that a server will 
be used with such amonitor, the server should exit immediately on completion. For 
such servers, rpcgen should be used with -k -1. 

“1 Compile into client-side stubs. 

-m Compile into server-side stubs, but do not generate a main routine This option is 
useful for doing callback-routines and for users who need to write their own main 
routine to do initialization. 

-n netid Compile into server-side stubs for the transport specified by neti d. There should be 
an entry for neti d in thenetconfig database. This option may be specified more 
than once, so as to compile a server that serves multiple transports. 

-N Use the newstyle of rpcgen. This allows procedures to have multiple arguments. It 
also uses the style of parameter passing that closely resembles C. So, when passing an 
argument to aremote procedure, you do not have to pass a pointer to the argument 
but the argument itself. This behavior is different from the old style of rpcgen- 
generated code. The new style is not the default case because of backwards 
compatibility. 

-o outfile Specify the name of the output file. If noneis specified, standard output is used (-c, 
-h, -1, -m, -n, -s, -sc, -ss, and -t modes only). 
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-s nettype 


-Sc 


-SS 


NOTES 


Compile into server-side stubs for all the transports bdonging to the class nettype. 
The supported classes are netpath, visible, circuit_n, circuit_v, datagram_n, 
datagram_v, tcp, and udp. See rpc(3N ) for the meanings associated with these 
classes. This option may be specified more than once. N ote: The transports are 
chosen at runtime and not at compile time 

Generate sample code to show the use of remote procedure and how to bind to the 
server before calling the client-side stubs generated by rpcgen. 

Generate skdeton code for the remote procedures on the server side. You would 
need to fill in the actual code for the remote procedures. 


Compileinto RPC dispatch table. 


Generate the code to support RPC dispatch tables. The options -c, -h, -1, -m, u, 
and -t are used exclusively to generate a particular type of file while the options -p 
and -T are global and can be used with the othe options. 


The RPC language does not support nesting of structures. As a workaround, structures can be declared at the top leva, and 
their name used inside other structures in order to achieve the same effect. N ame clashes can occur when using program 
definitions because the apparent scoping does not really apply. M ost of these can be avoided by giving unique names for 
programs, versions, procedures, and types. T he server code generated with the -n option refers to the transport indicated by 


netid and henceis very site-specific. 


EXAMPLE 
The following example: 
$ rpcgen -T prot.x 


generates five files: prot.h, prot_clnt.c, prot_svc.c, prot_xdr.c, and prot_tbl.i. 


This example 
$ rpcgen -h prot.x 


sends theC data-definitions (header file) to the standard output. 
To send the test version of the -pTesT, server-side stubs for all the transport bdonging to the class datagram_n to standard 


output, use 
$ rpcgen -s datagram_n -DTEST prot.x 


To create the server-side stubs for the transport indicated by netid tcp, use 


$ rpcgen -n tcp -o prot_svc.c prot.x 


SEE ALSO 
cc(1). 


rsh 


rsh— Remote shell 


SYNOPSIS 


rsh [-Kdnx] [-k realm] [-1 username] host command 


DESCRIPTION 


rsh executes command ON host. 
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rsh copies its standard input to the remote command, the standard output of the renote command to its standard output, 
and the standard error of the ranote command to its standard error. Interrupt, quit, and terminate signals are propagated to 
the renote command; rsh normally terminates when the renote command does. The options are as follows: 


-K Turns off all Kerberos authentication. 

-d Using setsockopt(2), turns on socket debugging on the T CP sockets used for communication with the renote 
host. 

-k Causes rsh to obtain tickets for the remote host in realm instead of the remote host's realm as determined by 
krb_realmofhost(3). 

-1 By default, the renote username is the same as the local username. The -1 option allows the renote name to be 
specified. K erberos authentication isused, and authorization is determined asin riogin(1). 

-n The -n option redirects input from the special device. (See the “Bugs” section of this manual page.) 

-x The -x option turns on DES encryption for all data exchange This may introduce a significant delay in response 
time. 


If no command is specified, you will be logged in on the remote host using r1ogin(1). 


Shel metacharacters that are not quoted are interpreted on local machine, while quoted metacharacters are interpreted on 
the renote machine For example, the command: 


rsh otherhost cat remotefile >> localfile 


appends the remote file remotefile to the local file localfile, while 


rsh otherhost cat remotefile >> other remotefile 
appends remotefile tO other remotefile. 


FILES 


/etc/hosts 


SEE ALSO 


rlogin(1), kerberos(3), krb sendauth(3), krb_realmofhost(3) 


HISTORY 
Thersh command appeared in BSD 4.2. 


BUGS 


If you are using csh(1) and put arsh in the background without redirecting its input away from the terminal, it will block 
even if no reads are posted by the remote command. If no input is desired you should redirect theinput of rsh to using the 
-n option. 


You cannot run an interactive command (rogue(6) or vi(1), for example) using rsh; use rlogin(1) instead. 


Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too complicated to 
explain here. 


BSD 4.2, 24 July1991 


rstart 


rstart— A sample implementation of a Remote Start client 


SYNOPSIS 


rstart [-c context] [-g] [-l username] [-v] hostname command args ... 
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DESCRIPTION 


rstart isasimpleimplementation of a Remote Start client as defined in “A Flexible Remote Execution Protocol Based on 
rsh.” It uses rsh as its underlying remote execution mechanism. 


OPTIONS 


-c context This option specifies the cont ext in which the command isto berun. A context specifies a general 
environment the program isto be run in. The details of this environment are host-specific; the intent is 
that the client need not know how the environment must be configured. If omitted, the context defaults to 
x. This should be suitable for running x programs from the host's “usual” x installation. 

-g Interprets command aS ageericcommand, as discussed in the protocol document. T hisis intended to allow 
common applications to be invoked without knowing what they are called on the remote system. 
Currently, the only generic commands defined are Terminal, LoadMonitor, ListContexts,and 


ListGenericCommands. 
-1 username This option is passed to the underlying rsh; it requests that the command be run as the specified user. 
“Vv This option requests that rstart be verbose in its operation. Without this option, rstart discards output 


from the remotes rstart helper, and directs the rstart hdper to detach the program from thersh 
connection used to start it. With this option, responses from the hdper are displayed and the resulting 
program isnot detached from the connection. 
NOTES 
This is atrivial implementation. Far more sophisticated implementations are possible and should be developed. 


Error-handling is nonexistent. W ithout -v, error reports from the remote are discarded silently. With -v, error reports are 
displayed. 


The spispLay environment variable is passed. If it starts with a colon, theloca hostnameis prepended. The local domain 
nameshould be appended to unqualified hostnames, but isn’t. 


The $SESSION_MANAGER environment variable should be passed, but isn’t. 
x11 authority information is passed for the current display. 


tce authority information should be passed, but isn’t. It isn’t completely clear how rstart should select what ICE authority 
information to pass. 


Even without -v, thesample rstart helper will leavea shal waiting for the program to complete. T his causes no real harm 
and consumes relatively few resources, but if it isundesirable it can be avoided by explicitly specifying the exec command to 
the shell, for example, @ rstart somehost exec xterm. 


Thisis obviously dependent on the command interpreter being used on the remote system; the example given will work for 
the Bourneand C shdls. 


SEE ALSO 


rstartd(1), rsh(1), “A Flexible Ranote Execution Protocol Based on rsh” 


AUTHOR 
Jordan Brown, Quarterdeck 0 ffice Systems 


X Verdon 11 Reease 6 
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rstartd— A sampleimplementation of a Remote Start rsh helper 


rstartd 


SYNOPSIS 


rstartd 


rstartd.real [-c configfilename ] 


DESCRIPTION 


rstartd iS an implementation of aRemote Start “helper” as defined in “A Flexible Remote Execution Protocol Based 
On rsh.” 


This document describes the peculiarities of rstartd and how it is configured. 


OPTIONS 


-c configfilename This option specifies the globa1 configuration filethat rstarta isto read. Normally, rstartd isa 
shell script that invokes rstartd.rea1 with the -c switch, allowing local configuration of the 
location of the configuration file If rstartd. rea is started without the -c option, it reads 
<XRoot>/1ib/X11/rstart/config, where <xRoot> refers to the root of the X11 install tree. 


INSTALLATION 


It iscritical to successful interoperation of the Remote Start protocol that rstartd be installed in a directory that isin the 
default search path, so that default rsh requests and the ik will be ableto find it. 


CONFIGURATION AND OPERATION 


rstartd is by design highly configurable. O ne would like things like configuration file locations to be fixed, so that users and 
administrators can find them without searching, but reality is that no two vendors will agree on where things should go, and 
nobody thinks the original location is “right.” Thus, rstartd allows the relocation of all of its files and directories. 


rstartd has a hierarchy of configuration files that are executed in order when a request is made. T hey are global config, per- 
user (“local”) config, global per-context config, per-user (“local”) per-context config, config from request. 


As you might guess from the presence of config from request, all of the config files are in the format of an rstart request. 
rstartd defines a few additional keywords with the INTERNAL - prefix for specifying its configuration. 


rstartd starts by reading and executing the global config file. This file will normally specify the locations of the othe 
configuration files and any system-wide defaults. 


rstartd will then read the user’s local config file default name $HoME/.rstart. 
rstartd will then start interpreting the request. 
Presumably, one of the first lines in the request will be acontext line The context name is converted to lowercase. 





rstartd will read the global config file for that context, default name <xRoot>/1ib/xX11/rstart/contexts/<name>, if any. 
It will then read theuser’s config file for that context, default name $HomE/.rstart.contexts/<name>, if any. 
(If neither of these exists, rstartd aborts with a Failure message ) 


rstartd will finish interpreting the request, and execute the program specified. T his allows the system administrator and the 
user a large degree of control over the operation of rstartd. The administrator has final say, because the global config file 
doesn’t need to specify a pe-user config file. If it does, however, the user can override anything from the global file, and can 
even completely replace the global context cont ig files. 


The config files have a somewhat more flexible format than requests do; they are allowed to contain blank lines and lines 
beginning with # are comments and ignored. (#s in the middle of lines are data, not comment markers.) 
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Any commands run are provided a few useful pieces of information in environment variables. The exact names are 
configurable, but the supplied defaults are 


$RSTART_CONTEXT The name of the context 
$RSTART_GLOBAL_CONTEXTS The global contexts directory 
$RSTART_LOCAL_CONTEXTS The local contexts directory 
$RSTART_GLOBAL_COMMANDS The global generic commands directory 
$RSTART_LOCAL_COMMANDS The local generic commands directory 


$RSTART_{GLOBAL, LOCAL}_ CONTEXTS should contain one special file @List, which contains alist of the contexts in that 
directory in the format specified for Listcontexts. T he supplied version of ListContexts will cat both the global and local 
copies of @List. 


Generic commands are searched for in several places: (defaults) 


Per-user pe-context directory $HOME /. rstart . commands /<context> 
Global pe-context directory <XRoot>/1ib/X11/rstart/commands /<context> 
Per-user all-contexts directory $HOME/.rstart.commands 


Global all-contexts directory (<xRoot>/1ib/X11/rstart/commands) 


(Yes, this means you can’t have an all-contexts generic command with the samenameas a context. It didn’t seem like abig 
deal.) 


Each of these directories should havea file called @List that gives the names and descriptions of the commands in that 
directory in the format specified for ListGenericCommands. 


CONFIGURATION KEYWORDS 


There are several special rstart keywords defined for rstarta configuration. U nless otherwise specified, there are no 
defaults; related features are disabled in this case. 


Internal-Registries name...— Givesaspace-separated list of misc registries that this system understands. (Registries 
other than these are accepted but generate a warning.) 


Internal-Local-Default relative filename— Gives thename($HoME relative) of the per-user config file. 

INTERNAL -GLOBAL-CONTEXTS absolute_directory_name— Gives thename of the system-wide contexts directory. 
INTERNAL -LOCAL -CONTEXTS relative _directory_name— Givesthename($Home relative) of the per-user contexts directory. 
INTERNAL -GLOBAL-COMMANDS absolute_directory_name— Gives thename of the system-wide generic commands directory. 


INTERNAL -LOCAL -COMMANDS relative _directory_name— Givesthename($Home rdative) of the per-user generic com- 
mands directory. 


INTERNAL - VARIABLE -PREFIX prefix— Gives the prefix for the configuration environment variables rstartd passes to its 
kids. 
INTERNAL -AUTH- PROGRAM authscheme program argv[®] argv[1]...— Specifies the program to run to set up authentica- 


tion for the specified authentication scheme program argv[@] ... givesthe program to run and its arguments, in the same 
form as the Exec keyword. 


INTERNAL -AUTH- INPUT authscheme— Specifies the data to be given to the authorization program asits standard input. Each 
argument is passed as a single line $n, wheren isanumbe,, is replaced by thenth argument to the auTH authscheme arg1 
arg2 ... line 





INTERNAL-PRINT arbitrary text— Printsits arguments as a D eoug message. M ostly for rstartd debugging, but could be 
used to debug config files. 


rstartd 471 


NOTES 


When usingtheC shal, or any other shell that runs a script every time the shell is started, the script may be run several 
times. In the worst case, the script may be run three times: By rsh, to run rstarta; by rstartd, to run the specified 
command; by the command, such as xterm. 


rstartd Currently limits lines, both from config files and requests, to BuFs1z bytes. 

DETACH isimplemented by redirecting file descriptors @, 1, and 2 to /dev/nu11 and forking before executing the program. 
cmp isimplemented by invoking $sHELL (default /bin/sh) with -c and the specified command as arguments. 

POSIX -UMASK is implemented in the obvious way. 


The authorization programs are run in the same context as the target program— same environment variables, path, and so 
on. Long term, this might bea problem. 


In the x context, GENERIC-CMD Terminal runs xterm. In the OpenWindows context, GENERIC-CMD Terminal runs cmdtool. 


In the x context, GENERIC-CMD LoadMonitor runs xload. In the OpenWindows context, GENERIC-CMD LoadMonitor runs 
perfmeter. 


GENERIC-CMD ListContexts lists the contents of @List in both the system-wide and per-user contexts directories. It is 
available in all contexts. 


GENERIC-CMD ListGenericCommands lists the contents of eList in the system-wide and per-user commands directories, 
including the per-context subdirectories for the current context. It is available in all contexts. 


CONTEXT None isnot implemented. 
CONTEXT Default iSreally dull. 


For installation ease, the contexts directory in the distribution contains a file @Aliases, which lists a context name and 
aliases for that context. T his file is used to make symlinks in the contexts and commands directories. 


All misc values are passed unmodified as environment variables. 


You can mistreat rstartd in any number of ways, resulting in anything from stupid behavior to core dumps. O ther than by 
explicitly running programs, | don’t think it can write or ddete any files, but there’s no guarantee of that. The important 
thing is that (a) it probably won't do anything REALLY stupid and (b) it runs with the user’s permissions, so it can’t do 
anything catastrophic. 

@List files need not be complete; contexts or commands that are dull or which need not or should not be advertised need 
not be listed. In particular, per-user @List files should not list things that are in the system-wide @ist files. In the future 
perhaps ListContexts and ListGenericCommands will automatically suppress lines from the system-wide files when there are 
per-user replacements for those lines. 


Error-handling isOK to weak. In particular, no attempt is made to properly report errors on the exec itself. (Perversdly, exec 
errors could be reliably reported when detaching, but not when passing the stdin/out socket to the app.) 


If compiled with -popT1_DISPLAY_HACK, rstartd will work around abugin sco opt version 1. (1.1?) (The bug isthat thex 
clients are all compiled with a bad library that doesn’t know how to look hostnames up using DNS. Thefix isto look up a 
hostnamein spispLay and substitute an rp address.) Thisisa trivial example of an incompatibility that rstart can hide. 


SEE ALSO 


rstart(1), rsh(1), “A Flexible Remote Execution Protocol Based on rsh” 
AUTHOR 
Jordan Brown, Quarterdeck 0 ffice Systems 
X Version 11 Release 6 
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rup 


rup— Remote status display 


SYNOPSIS 


rup [-dhlt] [host ...] 


DESCRIPTION 
rup displays a summary of the current system status of a particular host or all hosts on the local network. The output shows 
the current time of day, how long the system has been up, and the load averages. The load average numbers give the number 
of jobs in the run queue averaged over 1, 5 and 15 minutes. 
The following options are available: 
-d For each host, report what its local timeis. This is useful for checking time synchronization on a network. 
-h Sort the display alphabetically by hostname 
“1 Sort the display by load average. 
-t Sort the display by up time 
Therpe.rstatd(8) daemon must be running on the remote host for this command to work. rup uses an RPC protocol 
defined in /usr/include/rpcsvc/rstat.x. 


EXAM PLE 


example% rup otherhost 
otherhost up 6 days, 16:45, load average: 0.20, 0.23, 0.18 
example% 


DIAGNOSTICS 
rup: RPC: Program not registered— The rpc.rstatd(8) daemon has not bem started on the ranote host. 


rup: RPC: Timed out— A communication error occurred. Either the network is excessively congested, or the 
rpc.rstatd(8) daanon hasteminated on the remote host. 


rup: RPC: Port mapper failure - RPC: Timed out—Theremote host isnot running the portmapper (see portmap(8) 
man page), and cannot accommodate any RPC -based services. The host may be down. 


SEE ALSO 


ruptime(1), portmap(8), rpc.rstatd(8) 


HISTORY 


The rup command appeared in SunO S. 
BSD 4.3, 7 June1993 


rusers 


rusers— O utput who is logged in to machines on local network 


SYNOPSIS 


rusers [-al] [host ...] 


DESCRIPTION 


The rusers command produces output similar to who, but for the list of hosts or all machines on the local network. For each 
host responding to the rusers query, the hostname with the names of the users currently logged on is printed on each line. 
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The rusers command will wait for one minute to catch late responders. 
The following options are available: 


-a Print all machines responding even if no oneis currently logged in. 


“1 Print along format listing. T his includes the username, hostname, tty that the user islogged in to, the date and 
time the user logged in, the amount of time since the user typed on the keyboard, and the renote host the user 
logged in from (if applicable). 


DIAGNOSTICS 
rusers: RPC: Program not registered— T h@rpc.rusersd(8) daemon has not bem started on the ranote host. 


rusers: RPC: Timed out—A communication error occurred. Either the network is excessively congested, or the 
rpc.rusersd(8) daanon has terminated on the remote host. 


rusers: RPC: Port mapper failure - RPC: Timed out—Theramote host is not running the portmapper (see 
portmap(8) for more information), and cannot accommodate any RPC -based services. The host may be down. 


SEE ALSO 


rwho(1), users(1), who(1), portmap(8), rpc. rusersa(8) 


HISTORY 


The rusers command appeared in SunOS. 


BUGS 
The sorting options are not implemented. 
BSD 4.2, 23 April 1991 


rwall 
rwal1— Send a message to users logged on a host 


SYNOPSIS 


rwall host 


DESCRIPTION 


The rwall command sends a message to the users logged in to the specified host. The message to be sent can be typed in and 
terminated with Eor or it can bein afile 


DIAGNOSTICS 
rwall: RPC: Program not registered— T h@rpc.rwalld(8) daemon has not been started on the remote host. 


rwall: RPC: Timed out—A communication error occurred. Either the network is excessively congested, or the 
rpc.rwalld(8) daanon hasteminated on the remote host. 


rwall: RPC: Port mapper failure - RPC: Timed out—Theremote host isnot running the portmapper, and cannot 
accommodate any RPC -based services. The host may be down. 


SEE ALSO 


wall(1), portmap(8), rpc. rwalla(8) 
HISTORY 
The rwall command appeared in SunOS. 
BSD 4.2, 23 April 1991 
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rwho 
rwho— O utput who is logged in on local machines 


SYNOPSIS 


rwho -a 


DESCRIPTION 


The rwho command produces output similar to who, but for all machines on the local network. If no report has ben received 
from a machine for 11 minutes, then rwho assumes the machine is down, and does not report users last known to be logged 
in to that machine 


If a user hasn't typed to the system for a minute or more, then rwho reports this idle time. If a user hasn’t typed to the system 
for an hour or more, then the user will be omitted from the output of rwho unless the -a flag is given. 


FILES 


/var/rwho/whod. * Information about other machines 


SEE ALSO 


finger(1), rup(1), ruptime(1), rusers(1), who(1), rwnod(8) 


HISTORY 
The rwho command appeared in BSD 4.3. 


BUGS 


This is unwieldy when the number of machines on the local net is large. 
BSD 4.2, 23 April 1991 


script 


script— M ake typescript of terminal session 


SYNOPSIS 


script [-a] [file] 


DESCRIPTION 


script makes atypescript of everything printed on your terminal. It is useful for students who need a hardcopy record of an 
interactive session as proof of an assignment, as the typescript file can be printed out later with 1pr(1). 


If the argument file is given, script saves all dialogue in file If no filename is given, the typescript is saved in thefile 
typescript. 

O ption: 

-a Append the output to file or typescript, retaining the prior contents 


The script ends when the forked shdl exits (a control -p to exit the Bourne shall, sh(1), and exit, logout, or control -d (if 
ignoreeof isnot set) for the C-shdl, csh(1)). 


Certain interactive commands, such as vi(1), create garbage in the typescript file Script works best with commands that do 
not manipulate the screen; the results are meant to emulate a hardcopy terminal. 


ENVIRONMENT 
The following environment variable is utilized by script: 


SHELL If the variable SHELL exists, the shal forked by script will be that shdl. If SHELL is not set, the Bourne shal is 
assumed. (M ost shells set this variable automatically.) 


SEE ALSO 


esh(1) (for the history mechanism) 


HISTORY 


The script command appeared in BSD 3.0. 
BUGS 
script places everything in the 10g file including linefeeds and backspaces. T his is not what the naive user expects. 
BSD 4, 27 July 1991 


sed— Stream-oriented editor 
SYNOPSIS 
sed [ -hnV ][-e script ][-f script-file ][--help ][--quiet ][--silent ] 
[--version][--expression=script ][--file=script-file ][file ... ] 
DESCRIPTION 


sed reads the specified files or the standard input if no files are specified, makes editing changes according to a list of 
commands, and writes the results to the standard output. 


OPTIONS 

-h, --help Print a usage message on standard output and exit successfully. 

-n, --quiet, --silent Suppress the default output. sed only displays lines explicitly specified for 
output with the p command or the p flag of thes command. The default 
behavior isto echo each line of input, after edits, to the standard output. 

-V, --version Print the version number on the standard output and exit successfully. 

-e script, --expression=script Append one or more commands specified in the stringscri pt to thelist of 
commands. If there is just one -e option and no -f options, the -e flag may 
be omitted. 

-f script-file, --file=script-file Append the editing commands from scri pt- file to thelist of commands. 


Multiple -e and -¢ commands may be specified. Scripts are added to the list of commands to execute in the order specified, 
regardless of their origin. 


USAGE 
OPERATION 


sed operates as follows: 


Each line of input, not including its teminating newline character, is successively copied into a pattern space (a 
temporary buffer). 


All editing commands whose addresses match that pattern space are sequentially applied to the pattern space. 


476 Part |: User Commands 


W hen reaching the end of the command list, the pattern space is written to the standard output (except under -n) with 
an appended newline. 


The pattern space is cleared and the process is repeated for each line in the input. 
With sea, original input files remain unchanged because editing commands only modify a copy of the input. 
Some sed commands use a hold space to save all or part of the pattern space for later retrieval. 


COMMAND SYNTAX 
A sed script consists of commands with the general form: 
[address[, address ]][!]command [arguments ] 
Typically, there is only onecommand per line, but commands may also be concatenated on a single line by semicolons. 
W hitespace characters may be inserted before the first address and the command portions of the script command. 


ADDRESSES 
A sed command, as indicated, can specify zero, one, or two addresses. An address can be 


A line number, represented in decimal. The internal line number count maintained by sed is cumulative across input 
files and is not reset for each input file 


A pattern that is a regular expression, represented by nc patternc, wherec is any character except backslash (\) or 
newline In the address nxabenxdefx, the second x stands for itself, so the regular expression is abcxdef. H owever, the 
preferred (and equivalent) method to construct a regular expression is to enclose the pattern in sashes— /pattern/. 
Additionally, \n can be used to match any newlinein the pattern space except for the final newline character. 


A $ character that addresses the last line of input. 


GNU sed also implements a new type of address. T he address has form n ~m, which matches any line where the line 
number modulo misequal ton modulo m.If mis @ or missing, then 1 is used in its place. T his feature is not specified by 
POSIX. 


The following rules apply to addressed commands: 
A command line with no address sdects each input line. 


A command line with one address selects any line matching the address. Several commands accept only one address: =, a, 
i, r,and q. 


A command line with two comma-separated addresses selects the first matching line and all following lines up to and 
including the line matching the second address. If the second address starts before or is the same line as the first address, 
then only the first line is sdected. 


An address followed by : selects all lines that do not match the address. 
REGULAR EXPRESSIONS 
Regular expressions are patterns used in selecting text. For example, the seq command 





/string/p 
prints all lines containingst ring. 
In addition to specifying string literals, regular expressions can represent classes of strings. Strings thus represented are said to 


be matched by the corresponding regular expression. If it is possible for a regular expression to match several stringsin aline, 
then the leftmost longest match is the one selected. 


The following symbols are used in constructing search patterns: 

Thenull regular expression is equivalent to the last regular expression used. 
c Any character ¢ not listed here— including {, }, ,, <, >, |, and +— matches itself. 
\c Any backslash-escaped character c , except for {, }, ,, <, >, |, and +, matches itself. 
'-4n', M atches any single character except newline. 


[char-class] 


[*char-class ] 


\<, \> 


\(re\) 


\+ 


\ 
\{n ,m\} OF \{n ,\} OF \{n\} 


(\group\) 
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M atches any single character, other than newline inchar-class.1 0 includea] inchar- 
class, it must bethefirst character. A range of characters may be specified by separating the 
end characters of the range with a -, for example, a-z specifies the lowercase characters. The 
following literal expressions can also be used in char-cl ass to specify sets of characters: 
[:alnum:] [:cntrl:] [:lower:] [:space:] 

[:alpha:] [:digit:] [:print:] [:upper:] 

[:blank:] [:graph:] [:punct:] [:xdigit:] 

If - appears as the first or last character of char-cl ass, then it matches itsaf. All othe 
characters in char-cl ass match themselves. 

M atches any single character, other than newline notinchar-class.char-class iSdefined 
asin the preceding entry. 

If * isthe first character of a regular expression, then it anchors the regular expression to the 
beginning of aline Otherwise, it matches itself. 

If $ isthe last character of a regular expression, it anchors the regular expression to the end 
of aline Otherwise, it matches itself. 

Anchors the single character regular expression or subexpression immediately following it to 
the beginning (\<) or ending (\>)of a word, that is, in ASCII, amaximal string of 
alphanumeric characters, including the underscore (_). 

D efines a (possibly null) subexpression re. Subexpressions may be nested. A subsequent 
back reference of the form '\n', wheven isanumber in the range 1-9, expands to the text 
matched by the nth subexpression. For example, the regular expression \(a.c\)\1 matches 
the string 'abcabc', but not 'abcadc'. Subexpressions are ordered rdative to their left 
ddimiter. 

M atches the single character regular expression or subexpression immediately preceding it 
zero or more times. If * isthe first character of a regular expression or subexpression, then it 
matches itself. The * operator sometimes yields unexpected results. For example, the regular 
expression b* matches the beginning of the string 'abbb' (as opposed to the substring 
‘bbb ') because a null match is the only leftmost match. 

M atches the single character regular expression or subexpression immediately preceding it 
oneor more times. 


M atches the regular expression or subexpression specified before or after it. 


M atches the single character regular expression or subexpression immediately preceding it at 
least n and at most m times. If m is omitted, then it matches at least n times. If the commais 
also omitted, then it matches exactly n times. 


M atches the enclosed group of regular expressions. 





The following characters only have special meaning when used in replacement patterns: 


\ 


\n 


& 


COMMENTS 


Escape the following character. 


M atches the nth pattern previously saved byn(' and 'n), wheren isanumber from 0 to 9. 
Previously saved patterns are counted from theleftmost position on theline 


Prints the entire search pattern when used in areplacenent string. 


If the first nonwhite character in alineis a#), sea treats that line asa comment, and ignores it. If, however, the first such 


lineis of the form: 
#n 


sed runs as if the -n flag were specified. 
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GROUPING COMMANDS 


Braces ({, }) can be used to nest one address within another or to apply multiple commands to the same address: 


[address][, address] { 


command 1 command 2 ... 


} 


The opening { must end aline and the closing } must be on aline by itsaf. 


COMMANDS 


The maximum number of permissible addresses for each command is indicated in parentheses in the following list. 


An argument denoted text consists of one or more lines of text. If text islonger than onelinein length, then any newline 
characters must be hidden by preceding then with a backslash (\). 


An argument denoted read-filename OF write-filename must taminate the command line and must be preceded by 
exactly one space Each write -filename is created before processing begins. 


(0) 
(Q) #comment 


(0) : label 
(1) = 


(1)a\text 


(2) b label 


(2 


c\text 


(2) d 


(2) D 


(2) 
(2) 
(2) 
(2) 
(1) i\text 
(2) 1 


oF fF 2 


An empty command is ignored. 


Thelineisacomment and isignored by sea. If, however, the first such line in a script is of 
the form #n, then sea behaves asif the -n flag had been specified. 


Affix! abe! to alinein thescript for a transfer of control by b or t commands. 
W rite the current line number on the standard output as a line 


Append text following each line matched by the address on the standard output before 
reading the next input line 


Unconditionally transfer control to the: command bearing the! abe! .If nol abel is 
specified, then branch to the end of the script; no more commands are executed on the 
current pattern space. 


Change the pattern space by replacing the selected pattern with t ext . When multiple lines 
are specified, all lines in the pattern space are replaced with a single copy of t ext . Theend 
result is that the pattern space is deleted and no further editing commands can be applied 
to it. 


D elete the pattern space, preventing the line from being passed to the standard output, and 
start the next cycle 


D elete the initial segment of the pattern space through the first newline and start the next 
cycle. 


Replace the contents of the pattern space by the contents of the hold space 

Append a newline character followed by the contents of the hold space to the pattern space 
Replace the contents of thehold space by the contents of the pattern space 

Append a newline character followed by the contents of the pattern space to the hold space 
Insertt ext by writing it to the standard output. 


W rite the pattern space to standard output in a visually unambiguous form. N onprinting 
characters are displayed as ather three-digit octal values, preceded by a\, or as one of the 
following character constant escape sequences: 


\\ Backslash 

\a Alert 

\b Backspace 

\f Form-feed 

\n N ewline 

\r Carriage-return 
\t Tab 


\v Vertical tab 
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Long lines are folded, with the point of folding indicated by a backslash (\) and anewline 
character. The end of every line is marked with as. 


(2) n Copy the pattern space to the standard output. Replace the pattern space with the nett line 
of input. 

(2) N Append the nett line of input to the pattern space with an embedded newline (The current 
linenumber changes.) 

(2) p Print the pattern space to the standard output. 

(2) P Copy theinitial segment of the pattern space through the first newline to the standard 
output. 

(1) q Quit by transferring control to the end of the script and do not start a new cycle The 
pattern space is still written to the standard output. 

(2) r read-filename Read the contents of read- fil ename. Place them on the output before reading the next 
input line 

(2) s/regularexpression/  Substitutetherep! acement string for instances of ther egul ar expression in thepattern 

replacement /flags space. Any character may be used instead of /. (For a fuller description, see the explanation 


of replacenent patterns in the “Regular Expressions” section of this manual page.) flags is 
zero or more of: 


n Substitute for just the nth occurrence of the regular expression. 


g Globally substitute for all nonoverlapping instances of the regular expression 
rather than just the first one. 


p Print the pattern space if a reolacement was made. 
w write-filename Append the pattern space to write- filename if areplacenent was made. 


(2) t label Branch to the: command bearing the! abe! if any substitutions have been made since the 
most recent reading of an input line or execution of at. If! abe! is empty, branch to the 
end of the script. 


(2) wwrite-filename Append the pattern space to write-filename. 
(2) x Exchange the contents of the pattern and hold spaces. 
(2) y/stringl/string2/ Replace all occurrences of characters in st ri ng1 with the corresponding character in 





string2. Thelengthsofstring1 andstring2 must be equal. Any character other than '' 
or newline can be used instead of slash to delimit the strings. Withinstring1 andstring2, 
the ddimiter itsdf can be used asa literal character if it is preceded by a backslash. 


DIAGNOSTICS 
Command only uses one address— A command that takes one address had two addresses specified. 
Command doesn't take any addresses— A command that takes no addresses had an address specified. 
Extra characters after command— A command had extra text after the end. 


Unexpected End-of-file— Theend of ascript was reached before it should havebeen. This usually occurs when a 
command is started, but not finished. 


No previous regular expression—A metacharacter calling for a previous regular expression before any regular 
expressions were used. 


Missing command— An address was not followed by a command. 

Unknown command— A command was not one of the ones recognized by sea. 
Unexpected ','—A command had a spurious comma after an address. 
Multiple '!'s—Morethan one! (exclamation point) was used in acommand. 
Unexpected g—A g character was given in a command without a preceding f. 
Unexpected f—An f character was given in a command without a following g. 
} doesn't want any addresses— } should bealoneon aline 
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: doesn't want any addresses— The: command should not be preceded by an address. 

Unterminated s command—Thereplacenent field of thes command should be completed with a/ character. 
Multiple p options to s command —Th@p option was given morethan oncein an s command. 

Multiple g options to s command—Theg option was given morethan oncein an s command. 

Multiple number options to s command— M ore than onenumbe option was given to an s command. 
Unknown option to s—An unknown option was used for the s command. M aybe you shouldn’t do that. 


Strings for y command are different lengths—T here should bea oneto-one mapping between strings for the y 
command. 


Missing ' ' before filename— T here was no space bewem an r, w, or s///w command, and the filename specified for 
that command. 


Hopelessly evilcompiled in limit on number of open file. re-compile sed.— An attempt was made to open 
too many files, no matter how you look at it. 


SEE ALSO 
awk(1), ed(1), grep(1), per1(1), regex(3) 


HISTORY 


A sed command appeared in version 7 AT&T UNIX. 


STANDARDS 
GNU sea is expected to bea superset of the IEEE Std1003.2 (PO SIX) specification. 


CAVEATS 
GNU sea uses the PO SIX basic regular expression syntax. According to the standard, the meaning of some escape sequences 
is undefined in this syntax; notably \! and \+. 


Asin all GNU programs that use PO SIX basic regular expressions, sed interprets these escape sequences as metacharacters. 
So, x\+ Matches one or more occurrences of x. abc\ !def matches either abc or def. 


This syntax may cause problems when running scripts written for other versions of sed. Some sed programs have been 
written with the assumption that \! and \+ match the literal characters ! and +. Such scripts must be modified by removing 
the spurious backslashes if they are to be used with GNU sea. 


BUGS 


It haslong been noted that GN U sea ismuch slower than other implementations. The current bottleneck is the way sed 
reads and writes data files. It should read large blocks at a time (or even map files, where that is supported). When possible, it 
should avoid copying its input from one place in memory to another. Patches to make it do those things are welcome! 


Verdon 2.05, Decanbe 1994 


sessreg 


sessreg— M anageutmp/wtmp entries for non-init clients 


SYNOPSIS 
sessreg [-w wtmp-file] [-u utmp-file] [-1 line-name] [-h host- name] 
[-s slot-number] [-x Xservers-file] [-t ttys-file] [-a] [-d] user-name 
DESCRIPTION 


sessreg iSa simple program for managing utmp/wtmp entries for xdm sessions. 


eo i 


System V has a better interface to /etc/utmp than BSD; it dynamically allocates entries in the file instead of writing them at 
fixed positions indexed by position in /etc/ttys. 


To manage BSD -style utmp files, sessreg has two strategies. In conjunction with xdm, the -x option counts the number of 
linesin /etc/ttys and then adds to that the number of the linein the xservers file that specifies the display. T he display 
name must be specified as the! i ne- name using the -1 option. This sum is used as thes! ot- number in /etc/utmp that this 
entry will be written at. In the more general case, the -s option specifies thes! ot - number directly. If for some strange reason 
your systen uses a file other that /etc/ttys to manage init, the -t option can direct sessreg to look elsewhere for a count 
of terminal sessions. 


Conversdy, System V managers will never need to use these options (-x, -s, and -t). To make the program easier to 
document and explain, sessreg accepts the BSD -specific flags in the Systan V environment and ignores then. 





BSD also has ahost- name fidd in the utmp file that doesn’t exist in System V. This option is also ignored by the Systen V 
version of sessreg. 


USAGE 


In Xstartup, placea call like: 
sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 


and in Xreset: 
sessreg -d -1 $DISPLAY -x /usr/X11R6/1lib/xdm/Xservers $USER 











OPTIONS 

-w wt mp- file This specifies an alternate wtmp file, instead of /usr/adm/wtmp for BSD or /etc/wtmp for sysv. The 
special name none disables writing records to /usr/adm/wtmp. 

-uutmp-file This specifies an alternate utmp file instead of /etc/utmp. The special name none disables writing 
records to /etc/utmp. 

-1 line-name This describes the 1ine nameof the entry. For terminal sessions, thisis thefinal pathname segment 
of the terminal device filename (for example, ttydo). For x sessions, it should probably be the local 
display name given to the users session (for example, :a). If noneis specified, the terminal name 
will be determined with ttyname(3) and stripped of leading components. 

-h host-name This is set for BSD hosts to indicate that the session was initiated from a remote host. In typical 
xdm usage, this options is not used. 

-s sl ot-number Each potential session has a unique slot number in BSD systems; most are identified by the 
position of the! i ne- name in the /etc/ttys file This option overrides the default position 
determined with ttys -1ot(3). This option is inappropriate for use with xam, the -x option is more 
useful. 

-x Xservers-file Asx sessions are one-per-display, and each display is entered in this file this options sets thes | ot - 
number to bethe number of linesin thet t ys- file plus the index into thisfile that the! i ne- name 
is found. 

-t ttys-file This specifies an alternate file that the -x option will use to count the number of terminal sessions 
on ahost. 

-a This session should be added to utmp/wtmp. 

-d This session should be deleted from utmp/wtmp. -a or -d must be specified. 

SEE ALSO 

xdm(1) 

AUTHOR 


Keith Packard, MIT X Consortium 
X Version 11 Release 6 
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setterm 


setterm— Set terminal attributes 


SYNOPSIS 


setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 


setterm 


-term terminal name ] 

-reset ] 

-initialize ] 

-cursor [onjoff] ] 

-keyboard pc;jolivettijdutch;extended ] 
-repeat [onjoff] ] 


-appcursorkeys [onjoff] ] 





-linewrap [onjoff] ] 

-snow [onjoff] ] 

-softscroll [onjoff] ] 

-defaults ] 

-foreground black{redj green} yellow; blue ;jmagenta;cyan;white;de 
-background black; red; green, yellow, blue; magenta; cyan, white; de 
-ulcolor blackigrey;red; green; yellow; blue | magenta; cyan;white 
-ulcolor bright red;green; yellow; blue;magenta;cyan;white ] 
-hbcolor blackigrey;red; green; yellow; blue |magenta|cyan;white 
-hbcolor bright red;green; yellow; blue;magenta;cyan;white ] 
-inversescreen [onjoff] ] 

-bold [onjoff] ] 

-half-bright [onjoff] ] 

-blink [onj|off] 
-reverse [onjoff] ] 
-underline [onjoff] ] 
-store ] 
-clear [ alljrest ] ] 


-tabs [tab1 tab2 tab3 ... ] ] where (tabn = 1-160) 








-clrtabs [ tab1 tab2 tab3 ... ] where (tabn = 1-160) 





ault ] 


ault ] 


sgitopnm 


setterm [ -regtabs [ 1-160 ]] 
setterm [ -blank [ 0-60 ]] 
setterm [ -dump [ 1-NR CONS ]] 
setterm -append [ 1-NR CONS ]] 


setterm [ -file dumpfilename ] 





setterm [ -standout [ attr ]] 


DESCRIPTION 


setterm writes to standard output a character string that will invoke the specified terminal capabilities. W here possible, / 
etc/termcap is consulted to find the string to use. Some options, however, do not correspond to atermcap(5) capability. In 
this case, if the terminal type is minix-ve OF minix-vcam, the string that invokes the specified capabilities on the PC M inix 
virtual console driver is output. O ptions that are not implemented by the teminal are ignored. 


OPTIONS 
M ost options are self-explanatory. T he less obvious options are as follows: 
-term Can be used to override the TERM environment variable 
-reset Displays the terminal reset string, which typically resets the terminal to its power on state 


-initialize Displays the terminal initialization string, which typically sets the terminal's rendering options, and othe 
attributes to the default values 


-default Sets the terminal's rendering options to the default values 
-store Stores the terminal’s current rendering options as the default values 
Linux 0.98, 25 December 1992 

SEE ALSO 

tput(1), stty(1), termcap(5), tty(4) 
BUGS 

Differences between the M inix and Linux versions are not documented. 
AUTHORS 


Gordon Irlam (gordoni@cs.ua.oz.au); adaptation to Linux by Peter M acD onald; enhancements by M ika Liljeberg 
(1iljeber@cs.Helsinki.FI) 


Linux 0.98, 25 Decanber 1992 


sgitopnm 
sgitopnm— Convet an SGI image file to a portable anymap 


SYNOPSIS 


sgitopnm [-verbose] [SGI file] 


DESCRIPTION 


Reads an SGI image file as input. Producesa PGM image for a two-dimensional (one-channd) input file and aPPM image 
for a three- dimensional (three or more channels) input file. 
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OPTIONS 


-verbose Givesomeinformation about the SGI image file 


BUGS 
Probably 


REFERENCES 


SGI Image File Format documentation (draft v0.95) by Paul H aeberli (paul@sgi.com). Available via ftp at 
sgi.com: graphics /SGIIMAGESPEC. 


SEE ALSO 


pnm(5), pnmtosgi(1) 


AUTHOR 
Copyright© 1994 by Ingo Wilken (Ingo.Wilken@informatik.uni-oldenburg.de). 
29 January 1994 


shar 


shar— Create shell archives 


SYNOPSIS 


shar [ options ] file ... 
shar -S [ options ] 
DESCRIPTION 


shar Creates she11 archives (or shar files) that are in text format and can be mailed. T hese files may be unpacked later by 
executing then with /bin/sh. The resulting archive is sent to standard out unless the -o option is given. A wide range of 
features provide extensive flexibility in manufacturing shars and in specifying shar “smartness.” Archives may be “vanilla” or 
comprehensive. This manual page reflects shar version 4.0. 


OPTIONS 


O ptions havea one letter version starting with - or along version starting with --. The exceptions are - -help and - - 
version, which do not have short versions. O ptions can be given in any order. Some options depend on each other: The- o 
option is required if the -1 or -L option is used. 


The -n option is required if the -a option is used. 
See -v in thefollowing list. 
T hese are the available options: 


--version Print the version number of the program on standard output, then immedi- 
ately exit. 

--help Print ahap summary on standard output, then immediately exit. 

-V, --vanilla-operation Produce vanilla shars that rely only upon the existence of sed and echo in 


the unsharing environment. In addition, if test must also be supported if 
the -x option is used. The -v silently disables options offensive to the 
network cop (OF brown shirt), but does warn you if it is specified with -s, - 
z, -Z, -p, or -m (any of which does or might require uudecode, gzip or 
compress in the unsharing environment). 


har 


-v, --no-verbose Verbose or F. disables the inclusion of comments to be output when the 
archive is unpacked. 

-W, --no-character-count DoNOT check with we -c after unpack. The default is to check. 

-n name, --archive-name=name N ame of archive to be included in the header of the shar files. (See the -a 
switch.) 

-a, --net-headers Allows automatic generation of headers: 


Submitted by: who@where 
Archivename: <name>/part## 


The <name> must be given with the -n switch. If name includesa/, then / 
part isn’t used. Thus -n xyzzy produces the following: 


xyzzy/parto1 
xyzzy/parte2 
-n xyzzy/patch produces the following: 
xyzzy/patchot 
xyzzy/patcho2 
-n xyzzy/patcho1. produces the following: 
xyzzy/patcho1.01 
xyzzy/patch@1 .02 
T he whoewhere can be explicitly stated with the -s switch if the default isn’t 
appropriate. who@where is essentially built as ‘whoami'@'uname'. 
- 5 who@where, - -submitter=who@where Override automatically determined submitter name. 
-X, --no-check -existing O verwrite existing files without checking. If néther -x nor -x is specified, the 
unpack will check for and not overwrite existing files when unpacking the 
archive (unless -c is passed as a parameter to the script when unpacking). 


-X, --query-user Interactively overwrite existing files (D o not use for shars submitted to the 
Net.) 
-B, - -uuencode Treat all files as binary; use uuencode prior to packing. T his increases the size 


of thearchive. T he recipient must have uudecode in order to unpack. (U se of 
uuencode is not appreciated by many on theN et.) 

-T, --text-files T reat all files as text (default). 

-Z, --gzip Use gzip and uuencode on all files prior to packing. T he recipient must have 
uudecode and gzip (used with -d) in order to unpack. (U se of uuencode and 
gzip isnot appreciated by many on theN et.) 

-Z, -- compress Use compress and uuencode on all files prior to packing. T he recipient must 
have uudecode and compress (used with -d) in order to unpack. (Use of 
uuencode and compress iS not appreciated by many on theN et.) Option -c 
is synonymous to -z, but is being depreciated. 











-m, --no-timestamp Avoid generating touch commands to restore thefile modification dates 
when unpacking files from the archive 

-p, --intermix-type Allow positional parameter options. The options -s, -T, -z, and -z may be 
embedded, and files to the right of the option will be processed in the 
specified mode 

-g X, --level-for-gzip=X When doing compression, use -x aS a parameter to gzip. The -g option 
turns on the -z option by default. 

-b X, --bits-per-code=x When doing compression, use - bx aS a parameter to compress. The -B option 


turns on the -z option by default. 
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-M, - -mixed-uuencode Mixed mode. D eermine if the files are text or binary and archive correctly. 
Files found to be binary are uudecoded prior to packing. (U se of uuencode is 
not appreciated by many on theN et.) 

-P, --no-piping Use temporary files instead of pipes in the shar file. 

-¢, --cut-mark Start the shar with acut line A line saying cut here is placed at the start of 
each output file. 

-f, -- basename Restore by filename only, rather than path. This option causes only filenames 
to be used, which is useful when building a shar from several directories, or 
another directory. N ote that if a directory nameis passed to shar, the 
substructure of that directory will be restored whether -+ is specified or not. 

-d XXX, --here-delimiter=X XX Usexxx to ddimit the filesin the shar instead of sHar_Eor. T hisis for those 
who want to personalize their shar files. 

-F, --force-prefix Forces the pr efi x character (normally x unless the parameter to the -a 
option starts with x) to be prepended to every line even if not required. This 
option may slightly increase the size of the archive, especially if -B or -z is 
used. 

-0 XXX --output-prefix=XXX Save the archive to files xxx .01 through xxx .nn instead of standard out. 

M ust be used when the -1 or the -L switches are used. 

-1 XX --whole-size-limit=XX Limit the output file size to xxk bytes, but don’t split input files. 

-L XX --split-size-limit=xX Limit output file size to xxk bytes and split files if necessary. T he archives 
created with this option must be unpacked in correct order. 

-S --stdin-file-list Read list of files to be packed from the standard input rather than from the 
command line. Input must bein aform similar to that generated by the 
find command, one filename pe line This switch is especially useful when 
the command line will not hold the list of files to be packed. For example: 
find . -type f -print | sort | shar -S -Z -L50 -o /tmp/big 
If -p is specified on the command line then the options -B, -T, -z, and -z 
may beincluded in the standard input (on a line separate from filenames). 
The maximum number of lines of standard input, filenames, and options 
may not exceed 1024. 


EXAMPLES 


shar *.c > cprog.shar # all C prog sources 

shar -v *.[ch] > cprog.shar # non-verbose, .c and .h files 
shar -B -128 -oarc.sh *.arc # all binary .arc files, into 
# files arc.sh.@1 thru arc.sh.NN 

shar -f /lcl/src/u*.c > u.sh # use only the filenames 


WARNINGS 


No chmod or touch is ever generated for directories created when unpacking. T hus, if a directory is given to shar, the 
protection and modification dates of corresponding unpacked directory may not match those of the original. 


If a directory is passed to shar, it may be scanned more than once. T hedore, one should be careful not to change the 
directory while shar is running. 


Be careful that the output file(s) are not included in theinputs or shar may loop until the disk fills up. Be particularly careful 
whe adirectory is passed to shar that the output files are not in that directory (or a subdirectory of that directory). 


Use of the -B, -z, or -z, and especially -m, may slow the archive process considerably, depending on the number of files. 


Use of -x produces shars that will cause problems with many unshar procedures. U se this feature only for archives to be 
passed among agreeable parties. Certainly, -x is not for shall archives that are to be submitted to U senet. U sage of -B, -z, or 
-Z in Net shars will cause you to be flamed off the earth. N ot using -m or not using -F may also ge&t you occasional 
complaints. 
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SEE ALSO 


unshar(1) 


DIAGNOSTICS 


Thee are error messages for illegal or incompatible options; for nonregular, missing, or inaccessible files; or for (unlikely) 
memory allocation failure 


AUTHORS 


shar(3) is a derived work based on the efforts of the following: James Goding at CMU (decvax!microsof! uw-beave! jim), 
Michad A. Thompson, D alhousie U niversity, H alifax, N .S., Canada, Bill D avidsen (davidsen@sixhub), Richard H. 
Gumpertz (rhgacrs.com), Colas N ahaboo (colas@avahi.inria.fr), Bill Aten (bil1@netagw.com), Dennis Boylan 
(dennis%nanovx@gatech. edu), Warren Tucker (wht%n4hgf@gatech.edu), and other anonymous persons. J an D jfrv 
(jhd@irfu.se) created the man pages. 


27 September 1990 


shlock 


shlock— Create lock files for use in shell scripts 


SYNOPSIS 


shlock -p pid -f name [ -b ][-u ][-c ] 


DESCRIPTION 


shlock tries to create a lock file named name and write the process |D pid into it. If the file already exists, shlock will read 
the process ID from the file and test to see if the process is currently running. If the process exists, then the file will not be 
created. 


shlock exits with a zero status if it was able to create the lock file, or non-zero if the file refers to the currently active process. 


Process|D sare normally read and written in ASCII. If the -b flag is used, then they will be written as a binary int. For 
compatibility with other systems, the -u flag is accepted asa synonym for -b because binary locks are used by many uucp 
packages. 

The following example shows how shlock would be used within a shell script: 

LOCK=/news/lib/LOCK.send 

trap 'rm -f ${LOCK} ;exit1' 1 2 3 15 

if shlock -p $$ -f ${LOCK} ; then 

# Do appropriate work 

else 

echo Locked by ‘cat ${LOCK}' 

fi 

If the -c flag is used, then shlock will not create a lock file, but will instead use the file to see if thelock ishad by anothe 
program. If the lock is valid, the program will exit with anon-zero status; if the lock isnot valid (that is, invoking shlock 
without the flag would have succeeded), then the program will exit with a zero status. 


HISTORY 
Written by Rich $alz (rsalzeuunet .uu.net) after a description of HDB UUCP locking given by Peter H oneyman. 
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showrgb 


showrgb— Uncompile an RGB colorname database 


SYNOPSIS 


showrgb [ database ] 


DESCRIPTION 


The showrgb program reads an RGB colorname database compiled for use with the dbm database routines and converts it 
back to source form, printing the result to standard output. T he default database is the one that x was built with, and may be 
overridden on the command line. Specify the database name without the .pag or .dir suffix. 


FILES 
<XRoot>/1ib/X11/rgb Default database 
X Version 11 Release 6 


shrinkfile 

shrinkfile— Shrink a fileon a line boundary 
SYNOPSIS 

shrinkfile [ -s size ][-v ] file... 
DESCRIPTION 


The shrinkfile program shrinks files to a given size, preserving the data at the end of the file Truncation is performed on 
line boundaries, where a line is a series of bytes ending with anewline, \n. Thereisno linelength restriction and files may 
contain any binary data. 


Temporary files are created in the /tmp directory. T he Tupprr environment variable may be used to specify a different 
directory. 
A newline will be added to any nonempty file that does not end with anewline. The maximum file size will not be exceeded 
by this addition. 

By default, files are truncated to zero bytes. The -s flag may be used to changethe maximum size. Because the program 
truncates only on line boundaries, the final size may be may be smaller then the specified maximum. T he size parameter 
may end with ak, m, or g, indicating kilobyte (1024), megabyte (1048576) or gigabyte (1073741824) lengths. U ppercase 
letters are also allowed. The maximum file size is 2147483647 bytes. 








If the -v flag is used, then shrinkfile will print a status line if a file was shrunk. 


HISTORY 


Written by Landon Curt Noll (chongo@toad.com) and Rich $alz (rsalz@uunet .uu.net) for InterN €N ews. 


sirtopnm 


sirtopnm— Convet a Solitaire file into a portable anymap 


SYNOPSIS 


sirtopnm [sirfile] 
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DESCRIPTION 


Reads a Solitaire Image Recorder file as input. Produces a portable anymap as output. T he type of the output file deoends on 
the input file if it’s an MGI TYPE 17 file a pgm fileis written. If it’s an MGI TYPE 11 file a ppm fileis written. The 
program tells you which type it is writing. 


SEE ALSO 
pnmtosir(1), pnm(5) 
AUTHOR 
Copyright© 1991 by M arvin Landis. 
20 March 1991 


Size 


size— List section sizes and total size 


SYNOPSIS 
size [ -A | -B | --format=compatibility ][--help ] 
[ -d | -o | -x | --radix=number J] 
[ --target=bfdname ][-V | --version ] objfile ... 
DESCRIPTION 


TheGNU size utility lists the section sizes and the total size for each of the object files obj file in its argument list. By 
default, one line of output is generated for each object file or each module in an archive. 


OPTIONS 
-A, -B, --format compatibility Using one of these options, you can choose whether the output from GNU size 
resembles output from System V size (using -A, Of --format=sysv ), or Berkeley 
size (using -B Or - -format=berkeley) . T he default is the one-line format similar to 
Berkeley's. 
--help Show a summary of acceptable arguments and options. 
-d, -0, -x, --radix number Using one of these options, you can control whether the size of each section is given 


in decimal (-d, or --radix 10); octal (-o, Of --radix 8); or hexadecimal (-x, or 
--radix 16).IN --radix number, only the three values (8, 10, 16) are supported. 
The total size is always given in two radices: decimal and hexadecimal for -a or -x 
output, or octal and hexadecimal if you're using -o. 

--target bfdname You can specify a particular object-code format for objfile aSbfdname . Thismay 
not be necessary; size can automatically recognize many formats. (See ob jdump(1) 
for information on listing available formats.) 


-V, --version Display version number information on size itself. 
SEE ALSO 

binutils entry in info; TheGNU Binary Utilitie, Roland H. Pesch (October 1991); ar(1), objdump(1) 
COPYING 


Copyright© 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual, provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
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Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus Support, 5 N ovenber 1991 


Sldtoppm 


sldtoppm— Convet an AutoCAD slide file into a portable pixmap 


SYNOPSIS 


sldtoppm [-adjust][-dir][-height|-ysize s][-info][-lib|-Lib name][-scale s] 
[-verbose][-width|-xsize s][slidefile] 


DESCRIPTION 


sldtoppm reads an AutoCAD side file and outputs a portable pixmap. If no slidefile is specified, input isread from 
standard input. T he ppmdraw library is used to convert the vector and polygon information in the slide file to a pixmap; see 
the file ppmdraw.h for details on this package. 


OPTIONS 


-adjust If the display on which the slide file was created had nonsquare pixels, when the slide is processed with 
sldtoppm and the -adjust option is not present, the following warning will appear: warning - pixels on 
source screen were non-square. 

Specifying - adjust will correct image width to compensate. Specifying the -adjust option causes 
s1dtoppm to scale the width of the image so that pixdsin the resulting portable pixmap are square (and 
hence circles appear as true circles, not ellipses). T he scaling is performed in the vector domain, before 
scan-converting the objects. T heresults are, therefore, superior in appearance to what you’d obtain were 
you to perform the equivalent scaling with pnmscale after the bitmap had been created. 

-dir The input is assumed to bean AutoCAD slide library file A directory listing each slide in the library is 
printed on standard error. 

-height size  Scalestheimagein the vector domain so it issize pixdsin haght. If no -width or -xsize option is 
specified, the width will be adjusted to preserve the pixd aspect ratio. 


-info Dump the slide file header on standard error, displaying the original screen size and aspect ratio among 
othe information. 

-lib name Extracts the slide with the given name from theslide library given asinput. The specified name is converted 
to uppercase. 

-Lib name Extracts the slide with the given name from theside library given asinput. Thename is used exactly as 
specified; it is not converted to uppercase. 

-scale s Scales the image by factors, which may be any floating-point value greater than zero. Scaling is done after 


aspect ratio adjustment, if any. Because scaling is performed in the vector domain, before rasterization, the 
results look much better than running the output of s1dtoppm through pnmscale. 
-verbose Dumps the slide file header and lists every vector and polygon in the file on standard error. 


-width size Scales the imagein the vector domain, so it is size pixas wide If no -height or -ysize option is 
specified, the height will be adjusted to preserve the pixd aspect ratio. 


-xsize size Scales the imagein the vector domain so itissize pixds wide If no -height or -ysize option is specified, 
the haght will be adjusted to preserve the pixel aspect ratio. 


-ysize size Scales the image in the vector domain so it issize pixdsin haght. If no -width or -xsize option is 
specified, the width will be adjusted to preserve the pixd aspect ratio. 


All flags can be abbreviated to their shortest unique prefix. 


smproxy 
BUGS 


Only Level 2 slides are converted. Level 1 format has been obsolete since the advent of AutoCAD Release 9 in 1987 and was 
not portable across machine architectures. 


Slide library items with names containing 8-bit (such as!SO ) or 16-bit (Kanji, for example) characters may not be found 
when chosen with the -1ib option unless s1dtoppm has been built with character set conversion functions appropriate to the 
locale You can always retrieve slides from libraries regardless of the character set by using the -Lib option and specifying the 
precise name of library membe’. U se the -dir option to list the slidesin a library if you're unsure of the exact name. 


SEE ALSO 


AutoCAD Reference M anual: “Slide File Format”; pnmscale(1), ppm(5) 


AUTHOR 


John Walker 

Autodesk SA 

Avenue des C hamps-M ontants 14b 
CH-2074 MARIN 

Suisse Schwaiz/Svizzera/ Svizra/ Switzerland 
Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 

Voice 038/33 76 33 


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. T his software is provided “as is” without express or implied warranty. 


AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 
10 Octobe 1991 
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smproxy— Session M anager Proxy 


SYNOPSIS 
smproxy [-clientId id] [-restore saveFile] 
OPTIONS 
-clientId id Specifies the session |D used by smproxy in the previous session. 
-restore saveFile Specifies the file used by smproxy to save state in the previous session. 
DESCRIPTION 


smproxy allows x applications that do not support X11R6 session management to participate in an X11R6 session. 
In order for smproxy to act asa proxy for an x application, one of the following must be true: 


m = Theapplication maps a top-level window containing the wm_CLIENT_LEADER property. T his property provides a pointer 
to the client leader window that contains the wm_CLASs, WM_NAME, WM_COMMAND, and WM_CLIENT_MACHINE properties. 
or 


m@ Theapplication maps a top-level window that does not contain the wm_CLIENT_LEADER property. H oweve,, this top-levd 
window contains the wm_CLAss, WM_NAME, WM_COMMAND, and wM_CLIENT_MACHINE properties. 
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An application that supports the wm_Save_yoursELF protocol will receive a wM_SAVE_YouRSELF Client message each time the 
session manager issues a checkpoint or shutdown. This allows the application to save state. If an application does not 
support thewm_sAve_yourseLF protocol, then the proxy will provide enough information to the session manager to restart 
the application (using wm_commanp), but no state will be restored. 

SEE ALSO 
xsm(1) 


AUTHOR 
Ralph M or, X Consortium 


X Verdon 11 Rdease 6 


sort— Sort lines of text files 
SYNOPSIS 
sort [-cmus] [-t separator] [-o output-file] [-T tempdir] [-bdfiMnr] 
[+P0S1 [-PO0S2]] [-k POS1[,P0S2]] [file...] 
sort {--help, --version} 
DESCRIPTION 


This manual page documents the GN U version of sort. sort sorts, merges, or compares all the lines from the given files, or 
the standard input if no files are given. A filename of - means standard input. By default, sort writes the results to the 
standard output. 


sort has three modes of operation: sort (the default), merge, and check for sortedness. T he following options change the 
operation mode: 


-C Check whether the given files are already sorted; if they are not all sorted, print an error message and exit with a 
status of 1. 
-m M erge the given files by sorting them asa group. Each input file should already be individually sorted. It always 


works to sort instead of merge; merging is provided because it is faster, in the case where it works. 


A pair of lines is compared as follows: if any key fidds have been specified, sort compares each pair of fields, in the order 
specified on the command line, according to the associated ordering options, until a difference is found or no fields are left. 


If any of the global options Mbdfinr are given but no Key fidds are specified, sort compares the entire lines according to the 
global options. 


Finally, as a last resort when all keys compare equal (or if no ordering options were specified at all), sort compares the lines 
byte by bytein machine collating sequence. T he last resort comparison honors the -r global option. The -s (stable) option 
disables this last-resort comparison so that lines in which all fields compare equal are left in their original relative order. If no 
fidds or global options are specified, -s has no effect. 


GNU sort hasno limits on input line length or restrictions on bytes allowed within lines. In addition, if the final byte of an 
input fileisnot anewline, GNU sort silently suppliesone 


If the environment variable Tmpprr is set, sort uses it as the directory in which to put temporary files instead of the default, 
/tmp. The -T tempdir option is another way to select the directory for temporary files; it overrides the environment 
variable. 


The following options affect the ordering of output lines. T hey may be specified globally or as part of a specific key field. If 
no key fidds are specified, global options apply to comparison of entire lines; otherwise, the global options are inherited by 
key fields that do not specify any special options of ther own. 


-b Ignore leading blanks when finding sort keysin each line. 

-d Sort in phone directory order; ignore all characters except letters, digits, and blanks when sorting. 

-f Fold lowercase characters into the equivalent uppercase characters when sorting so that, for example, b is sorted 
the same way B is. 

-i Ignore characters outside the ASCII range 040-0176 octal (inclusive) when sorting. 

-M An initial string, conssting of any amount of whitespace followed by three letters abbreviating amonth name is 
folded to uppercase and compared in the order 'uAN' < 'FEB' < ... < 'DEC'. Invalid names compare low to 
valid names. 

-n Compare according to arithmetic value an initial numeric string consisting of optional whitespace, an optional - 
sign, and zero or more digits, optionally followed by a decimal point and zero or more digits. 

-r Reverse the result of comparison, so that lines with greater key values appear earlier in the output instead of later. 


O ther options are 


-o output-file W rite output to out put- file instead of to the standard output. If out put- file isoneof theinput 
files, sort copies it to atenporary file before sorting and writing the output to out put-file. 
-t separator Use character separator asthe field separator when finding the sort keys in each line By default, 


fidds are separated by the empty string between a nonwhitespace character and a whitespace 
character. T hat is to say, given the input line foo bar, sort breaks it into fields foo and bar. The 
fidd separator is not considered to be part of either the fidd preceding or the field following it. 


-u For the default case or the -m option, only output the first of a sequence of lines that compare 
equal. For the -c option, check that no pair of consecutive lines compares equal. 
+P0S1 [ -POS2] Specify a field within each line to use asa sorting key. T he fidd consists of the portion of theline 


starting at posi and up to (but not including) pos2 (or to the end of thelineif pos2 isnot given). 
The fields and character positions are numbered starting with o. 

-k POS1[,POS2] An alternate syntax for specifying sorting keys. The fidds and character positions are numbered 
carting with 1. 


A position has the form f.c, where ¢ isthe number of the field to use and c isthe number of the first character from the 
beginning of the field (for +pos) or from the end of the previous field (for -pos). The .c part of aposition may be omitted, 
in which case it is taken to be the first character in the field. If the -b option has been given, the .c part of afield specifica 
tion is counted from the first nonblank character of the fidd (for +pos) or from the first nonblank character following the 
previous fidd (for -pos). 


A +pos Or -pos argument may also have any of the option letters mbdfinr appended to it, in which case the global ordering 
options arenot used for that particular fidd. The -b option may be independently attached to either or both of the+pos and 
-pos parts of afield specification, and if it isinherited from the global options, it will be attached to both. If a-nor -m 
option is used, thus implying a -b option, the -b option is taken to apply to both the +pos and the - pos parts of a key 
specification. K eys may span multiple fields. 


In addition, when GN U join isinvoked with exactly one argument, the following options are recognized: 


--help Print a usage message on standard output and exit successfully 
--version Print version information on standard output, then exit successfully 
COMPATIBILITY 


Historical (BSD and System V) implementations of sort have differed in ther interpretation of some options, particularly 
-b, -f, and -n. GNU sort follows the PO SIX behavior, which is usually (but not always) like the System V behavior. 
According to PO SIX, -n no longer implies -b. For consistency, -m has been changed in the same way. T his may affect the 
meaning of character positionsin fidd specifications in obscure cases. If this bites you, the fix is to add an explicit -b. 


BUGS 
The different meaning of field numbers depending on whether -k is used is confusing. It’s all PO SIX’s fault! 
GNU Tet Utilities 
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spctoppm 


spctoppm— Convet an Atari compressed Spectrum file into a portable pixmap 


SYNOPSIS 


spctoppm [spcfile] 


DESCRIPTION 


spctoppm reads an Atari compressed Spectrum file as input and produces a portable pixmap as output. 
SEE ALSO 
sputoppm(1), ppm(5) 


AUTHOR 
Copyright© 1991 by Steve Baczyk (seb3e@gte.com) and J ef Poskanzer. 
19 July 1990 


split 


split— Split a file into pieces 


SYNOPSIS 
split [-lines] [-l lines] [-b bytes [bkm]] [-C bytes [bkm]] [--lines=lines ] 
[--bytes=bytes [bkm]] [--line-bytes=bytes[bkm]] [--help] [--version] 
[infile [outfile-prefix]] 

DESCRIPTION 


This manual page documents the GN U version of split. split creates one or more output files (as many as necessary) 
containing consecutive sections of the infile, or the standard input if none is given or the name - isgiven. By default, 
split puts 1000 lines of the input file or whatever is left if it is less than that, into each output file 


T he output filenames consist of a prefix followed by a group of letters, chosen so that concatenating the output filesin sorted 
order by filename produces the original input file in order. T he default output filename prefix is x. If the outfile- prefix 
argument is given, it is used as the output filename prefix instead. 


OPTIONS 
-lines, -1 lines, --lines=lines Put! ines lines of the input file into each output file 
-b bytes [bkm], --bytes=bytes [bkm] Put bytes bytes of the input file into each output file bytes isa non-zero 
integer, optionally followed by one of the following characters to specify a 
different unit: 


b 512-byte blocks 
k 1-kilobyte blocks 
m 1-megabyte blocks 

-C bytes [bkm], --line-bytes=bytes[bkm] | Putinto each output file as many complete lines of the input file as is 
possible without exceeding bytes bytes. If aline that is longer than bytes 
bytes occurs, put bytes bytes of it into each output file until less than byt es 
bytes of the line are left, then continue normally. bytes has the same format 
as for the - -bytes option. 


soutoppm 
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--help Print a usage message and exit with a non-zero status. 
--version Print version information on standard output then exit. 


spottopgm 


spottopgm— Convert SPOT satelite images to portable graymap format 


SYNTAX 
spottopgm [-1;2;3] [Firstcol Firstline Lastcol Lastline] inputfile 
OPTIONS 
-11213 Extract the given color from the SPOT image The colors are infrared, visible 


light, and ultra-violet, although | don’t know which corresponds to which 
number. If the image isin color, this will be announced on standard error. 
The default color is 1. 


Firstcol Firstline Lastcol Lastline Extract the specified rectangle from the SPOT image. M ost SPOT images are 
3,000 lines long and 3,000 or more columns wide. U nfortunately, the SPO T 
format only gives the width and not the length. T he width is printed on 
standard error. The default rectangle is the width of the input image by 3,000 
lines. 


DESCRIPTION 


spottopgm converts the named inputfile into portable graymap format, defaulting to the first color and the whole SPOT 
image unless specified by the options. 


INSTALLATION 


You must edit the source program and ather define BIGENDIAN OF LITTLEENDIAN, and fix the typedefs for uint32t, 
uint16t, and uintst appropriatdy. 


BUGS 


Currently, spottopgm doesn’t determine the length of the input file this would involve two passes over the input file. It 
defaults to 3,000 lines instead. 


spottopgm could extract a three-color image (ppm), but | didn’t feel like making the program more complicated than it is 
now. Besides, there is no one to-one correspondence between red, green, blue, and infra-red, visible and ultra-violet. 


I've had only a limited number of SPOT images to play with, and therefore wouldn’t guarantee that this will work on any 
other images. 


AUTHOR 


Warren T oomey (wkt@csadfa.cs.adfa.oz.au) 


SEE ALSO 


The rest of the pbmp1us suite. 


sputoppm 


sputoppm— Convet an Atari uncompressed Spectrum file into a portable pixmap 
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SYNOPSIS 


sputoppm [spufile] 


DESCRIPTION 
sputoppm reads an Atari uncompressed Spectrum file as input and produces a portable pixmap as output. 
SEE ALSO 
spctoppm(1), ppm(5) 
AUTHOR 
Copyright© 1991 by Steve Baczyk (seb3e@gte.com) and J ef Poskanzer. 
19 July 1990 


sq 
sq— Squeeze a sorted word list 
unsq— U nsqueeze a sorted word list 


SYNOPSIS 


sq <infile > outfile 
unsq < infile > outfile 


DESCRIPTION 
sq compresses a sorted list of words (a dictionary). For example, 
sort /usr/dict/words | sq | compress > words.sq.Z 
will compress dict by about a factor of 4. 
unsq uncompresses the output of sq. For example, 


compress -d < words.sq.Z | unsq | sort -f -o words 


will uncompress a dictionary compressed with sq. The squeezing is achieved by eliminating common prefixes and replacing 
them with asingle character that encodes the number of characters shared with the preceding word. T he prefix size is 
encoded as a single printable character: 0-9 represent 0-9, A-Z represent 10-35, and a-z represent 36-61. 


AUTHOR 
Mike W exler 


SEE ALSO 


compress(1), sort(1). 


Local 


startx 


startx— Initialize an x session 


SYNOPSIS 


startx [[client ] options ..] [-- [ server ] options ... ] 
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DESCRIPTION 


NOTE 


The startx script supplied with the X11 distribution is a sample designed more as a base for customization than as a fin- 
ished product. Site administrators are urged to customizeit for thar site— and to update this manual pagewhen they do. 


The startx script is afront end to xinit that provides a somewhat nicer user interface for running a single session of the X 
Window System. It istypically run with no arguments. 


To determine the client to run, startx first looks for afile called .xinitrc in the user’s home directory. If that is not found, 
it uses the file xinitre in the xinit library directory. If command-line client options are given, they override this behavior. 
To determine the server to run, startx first looks for a file called .xserverrc in the user’s home directory. If that is not 
found, it uses the file xserverrc in the xinit library directory. If command-line server options are given, they override this 
behavior. U sers rarely need to providea .xserverrc file. (See the xinit(1) manual page for more details on the arguments.) 


The .xinitre istypically a shal script that starts many clients according to the user's preference When this shell script exits, 
startx kills the server and performs any other session shutdown needed. M ost of the clients started by .xinitre should be 
run in the background. The last client should run in the foreground; when it exits, the session will exit. People often choosea 
session manager, window manager, or xterm as the “magic” client. 


EXAMPLE 


Following isa sample xinitrc that starts several applications and leaves the window manager running as the “last” applica- 
tion. Assuming that the window manager has been configured properly, the user then chooses the Exit menu item to shut 
down x. 





xrdb -load $HOME/.Xresources 
xsetroot -solid gray & 

xbiff -geometry -430+5 & 

oclock -geometry 75x75-0-0 & 
xload -geometry -80-0 & 

xterm -geometry +0+60 -1ls & 

xterm -geometry +0-100 & 

xconsole -geometry -Q+® -fn 5x7 & 


exec twm 
ENVIRONMENT VARIABLES 
DIsPLAY This variable gets set to thename of thedisplay to which clients should connect. N ote that this gets set, not read. 
FILES 
$(HOME) /.xinitre Client to run. Typically a shel script that runs many programsin the background. 
$ (HOME) /.xserverrc Server to run. The default is x. 
<XRoot>/1ib/X11/xinit/xinitre Client to run if the user hasno .xinitrc file. <xRoot> refers to the root of the X11 


install tree. 


<XRoot>/lib/X11/xinit/xserverre Client to run if the user has no. xserverrc file. This is only needed if the server 
needs special arguments or is not named. <xRoot> refers to the root of the X11 
install tree. 


SEE ALSO 


xinit(1) 
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strings 
strings— Print the strings of printable characters in files 
SYNOPSIS 
strings [ -a,-|--all ][-f|--print-file-name][-o ][--help ][-v;--version ] 
{ -n min-len |-min-len |--bytes= min-len ][-t 0,x,d ] 
[ --target=bfdname ] |--radix=0,x,d ] file 
DESCRIPTION 


Foreachfile given, GNU strings prints the printable character sequences that are at least four characters long (or the 
number given with the options below) and are followed by anuL or newline character. By default, it only prints the strings 
from the initialized data sections of object files; for other types of files, it prints the strings from the whole file. 


strings is mainly useful for determining the contents of nontext files. 


OPTIONS 


Thelong and short forms of options, shown hereas alternatives, are equivalent. 


-a, --all, - Do not scan only the initialized data section of object files; scan the whole 
files. 
-f, --print -file-name Print the name of the file before each string. 
--help Print asummary of the options to strings on the standard output and exit. 
-v, --version Print the version number of strings on the standard output and exit. 
-n min-len,-min-len, -bytes=mi n-|en Print sequences of characters that are at least mi n- 1 en characters long, instead 
of the default 4. 
-t 0,x,d, --radix=o,x,d Print the offset within the file before each string. The single character 
argument specifies the radix of the offset— octal, hexadecimal, or decimal. 
--target=bf dname Specify an object code format other than your system's default format. (See 
objdump(1), for information on listing available formats.) 
-0 Like -t o. 
SEE ALSO 
binutils etry in info; TheGNU Binary Utilitie, Roland H. Pesch (October 1991); ar(1), nm(1), objdump(1), rantib(1). 
COPYING 


Copyright© 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus Support, 25 June 1993 


grip 


strip 


strip— Discard symbols from object files. 


SYNOPSIS 


strip [ -Fofdname|--target=bfdname ] [ -Ibfdname, 
--input-target=bfdname ] [ -Obfdname|--output-target=bfdname ] 
[-Rsectionname |--remove-section=sectionname ] [ -s|--strip-all ] 
[-S{-g,--strip-debug ][-x,--discard-all ][-X;--discard-locals] 
[-vj--verbose ][-V|--version ][-V;--help ] objfile ... 


DESCRIPTION 


GNU strip discards all symbols from the object files obj file. Thelist of object files may include archives. At least one 
object file must be given. 





strip modifies the files named in its argument, rather than writing modified copies under different names. 


OPTIONS 
-F bfdname, --target=bf dname Treat the original obj file asafile with the object code format 
bf dname, and rewrite it in the same format. 
--help Show asummary of the options to strip and exit. 
-I bfdnamefdname", --input-target=bf dname Treat the original obj file asafile with the object code format 
bfdname. 
-O bfdname, --output-target=bf dname Replaceobj file with afilein the output format bf dname. 


-R sectionname, --remove-section=sectionname |Removethenamed section from the file This option may be given 
more than once. N ote that using this option inappropriately may 
make the object file unusable. 


-s, --strip-all Remove all symbols. 
-S, -g, --strip-debug Remove debugging symbols only. 
-x, --discard-all Remove nonglobal symbols. 
-X, --discard-locals Remove compiler-generated local symbols. (T hese usually start with L 
or a period. 
-v, -- verbose Verbose output: list all object files modified. In the case of archives, 
strip -V lists all members of the archive. 
-V, --version Show the version number for strip and exit. 
SEE ALSO 
binutils @try in info; TheGNU Binary Utilities, Roland H. Pesch (O ctober 1991) 
COPYING 


Copyright© 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnus Support, 5 N ovenber 1991 
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subst 


subst— Substitute definitions into file(s) 


SYNOPSIS 


subst [ -e editor ] -f substitu 


DESCRIPTION 


subst makes substitutions into fi 


ions victim... 


6s, in a way that is suitable for customizing software to local conditions. Each vi cti mfileis 


altered according to the contents of thesubstitutions file 


Thesubstitutions filecontains 
first field is the name of the subst 
editor metacharacters like & and \ 
#iSacomment and isignored. 





one line per substitution. A line consists of two fidds separated by one or more tabs. The 
tution, the second is the value. N either should contain the character #, and use of text- 
is also unwise; thename in particular is best restricted to albnanumaric. A line starting with 


In the victim files, each line on which a substitution is to be made (a target line) must be preceded by a prototype line The 
prototype line should be ddimited in such a way that it will be taken as a comment by whatever program processes the file 
later. The prototype line must contain a prototype of the target line bracketed by =()< and >()=; everything else on the 
prototype line isignored. subst extracts the prototype, changes all instances of substitution names bracketed by e< and >e to 
their values, and then replaces the target line with the result. 


Substitutions are done using the sed(1) editor, which must be found in either the /bin or /usr/bin directories. T 0 specify a 
different executable, use the -e flag. 


EXAMPLE 
If thesubstitutions fileis 


FIRST 111 
SECOND 222 


and the victim file is 


X =25 


/* =()<y =@<FIRST>@+@<SECOND>@;>()= */ 


y =88 +99; 
Z =5; 


then subst -f substitutions victim changes victim to 


xX =25 
/* =()<y =@<FIRST>@+@<SECOND>@;>()= */ 
y = 111 + 222; 
Z =5; 
FILES 


victimdir /substtmp.new N ew version being built 


victimdir/substtmp.old Old 


SEE ALSO 
sed(1) 


DIAGNOSTICS 


version during renaming 


Complains and halts if it isunable to create its temporary files or if they already exist. 


SuperP robe 


HISTORY 
Written at U niversity of T oronto by H enry Spencer. 
Rich $alz added the -e flag J uly, 1991. 


BUGS 


When creating a file to be substed, it’s easy to forget to insat adummy target line after a prototype line; if you forget, subst 
ends up deleting whichever line did in fact follow the prototype line 


Local 


sum 

sum— Checksum and count the blocks in a file 
SYNOPSIS 

sum [-rs] [--sysv] [--help] [--version] [file...] 
DESCRIPTION 


This manual page documents the GN U version of sum. sum computes a 16-bit checksum for each named file or the standard 
input if none are given or when afilenamed - isgiven. It printsthe checksum for each file along with the number of blocks 
in thefile (rounded up). By default, each corresponding filename is also printed if at least two arguments are specified. W ith 
the - -sysv option, corresponding filenames are printed when there is at least one file argument. By default, the anu sum 
computes checksums using an algorithm that is compatible with the BSD sum and prints file sizes in units of 1K blocks. 


OPTIONS 
-r Use the default (BSD -compatible) algorithm. This option isincluded for compatibility with the System V 
sum. Unless the -s option was also given, it has no effect. 
-8, --SYSV Compute checksums using an algorithm that is compatible with the one the Systen V sum uses by default 
and print file sizes in units of 512-byte blocks instead of 1K. 
--help Print a usage message and exit with a non-zero status. 
--version Print version information on standard output, then exit. 
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superProbe 
SuperProbe— Probe for and identify installed video hardware 
SYNOPSIS 
SuperProbe [-verbose] [-no16] [-excl list] [-mask10] [-order list] [-noprobe list] [-bios base] 
[-no bios] [-no dac] [-no mem] [-info] 
DESCRIPTION 


SuperProbe iS a program that will attempt to determine the type of video hardware installed in an EISA/ISA/VLB-bus 
system by checking for known registers in various combinations at various locations (M icroChannd and PCI machines may 
not be fully supported; many work with the use of the -no_bios option.) This isan error-prone process, especially on UN IX 
(which usually has alot more esoteric hardware installed than M S-D OS systems do), 90 SuperProbe may likely need help 
from the user. 
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SuperProbe runs on SVR3, SVR4, Linux, 386BSD /FreeBSD /N &BSD, M inix-386, and M ach. It should be trivial to extend 
it to work on any other UN IX-like operating system, and even non-UN IX operating systems. All of the operating systan 
(O S) dependencies are isolated to a single file for each OS. 


At this time, SuperProbe can identify MDA, Hercules, CGA, MCGA, EGA, VGA, and an entire horde of SVGA chipsets. 
(See the - info option under “O ptions.”) It can also identify several H iC olor/T rue-color RAM D ACsin useon SVGA 
boards, and the amount of video memory installed (for many chipsets). It can identify 8514/A and some derivatives, but not 
XGA, or PGC (although the author intends to add those capabilities). N or can it identify other esoteric video hardware (like 
Targa, TIGA, or M icrofidd boards). 


OPTIONS 


-verbose 
-no16 


-excl\l ist 


-mask10 


-order\list 


-noprobe\l i st 


-bios\base 


-no_bios 


-no_dac 
-no_mem 


-info 


EXAMPLES 


SuperProbe will be verbose and providelots of information as it does its work. 

SuperProbe will not attempt to use any ports that require 16-bit |/O address decoding. The original ISA 
bus only specified that |/O ports be decoded to 10 bits. Therefore, someold cards (including many 8-bit 
cards) will misdecode references to ports that use the upper 6 bits, and may get into funny states because 
they think that they are being addressed when they are not. It is recommended that this option be used 
initially if any 8-bit cards are present in the system. 

SuperProbe will not attempt to access any I/O ports on the specified exclusion list. Some video cards use 
rather nonstandard I/O ports that may conflict with other cards installed in your system. By specifying to 
SuperProbe, alist of ports already in use, it will know that there cannot be any video cards that use those 
ports, and hence will not probe them (which could otherwise confuse your hardware). T he exclusion list is 
specified as a comma-separated list of 1/O ports or port ranges. A range is specified asi ow-hi gh, and is 
inclusive. The ports can be specified in decimal, in octal (numbers begin with a), or hexadecimal (numbers 
begin with ox). 

This option is used in combination with -exc1. It tells superProbe that when comparing an |/O port 
under test against the exclusion list, the port address should be masked to 10 bits. Thisis important with 
older 8-bit cards that only do 10-bit decoding, and for some cheap 16-bit cards as well. This option is 
simply a less drastic form of the -no16 option. 

This option specifies which chipsets SuperProbe should test, and in which order. The 1ist parameter isa 
comma-separated list of chipset names. This list overrides the built-in default testing order. To find the list 
of acceptable names, use the - info option described later in this list. N ote that items displayed as 
“Standard video hardware” are not usable with the - order option. 

This option specifies which chipsets superProbe should not test. The order of testing will athe be the 
default order, or that specified with the -order option. The 1ist parameter is a comma-separated list of 
chipset names. To find the list of acceptable names, use the - info option. N ote that items displayed as 
“Standard video hardware” are not usable with the -noprobe option. 

This option specifies the base address for the graphics-hardware BIO S. By default, SuperProbe will 
attempt to locate the BIO S base on its own (the normal address is oxcooeo). If it fails to correctly locate 
the BIOS (an error message will be printed if this occurs), the -bios option can be used to specify the 
base. 

Disallow reading of the video BIOS and assume that an EGA or later (VGA, SVGA) board is present as 
the primary video hardware. 

Skip probing for the RAM DAC type whe an (S)VGA is identified. 

Skip probing for the amount of installed video memory. 

SuperProbe will print out a listing of all the video hardware that it knows how to identify. 


Torun SuperProbe in its most basic and automated form, simply enter the following: 


SuperProbe 


NOTE 


You may want to redirect stdout to a file when you run SuperProbe (especially if your OS does not support Virtual 
Terminals on the console). 


H owever, if you have any 8-bit cards installed, you should initially run superProbe as 
SuperProbe -verbose -no16 

(the - verbose option isincluded so you can see what superProbe is skipping). 

Finer granularity can be obtained with an exclusion list, for example, 

SuperProbe -verbose -excl 0x200,0x220-0x230,0x250 


will not test for any device that uses port ox200, ports @x220 through ox239, inclusive, or port @x250. If you have any 8-bit 
cards installed, you should add -mask1@ to thelist of options. 


To restrict the search to Western Digital, Tseng, and Cirrus chipset, run SuperProbe as follows: 


SuperProbe -order WD,Tseng,Cirrus 


BUGS 
Probably alot at this point. Please report any bugs or incorrect identifications to the author. 


It is possible that SuperProbe can lock up your machine. Be sure to narrow the search by using the -no16, -exc1, and - 
mask10 options provided to keep superProbe from conflicting with other installed hardware. 


SEE ALSO 
The vgadoc3.zip documentation package by Finn T hoegersen, availablein the M S-D OS archives of many FTP repositories. 
Programmer's Guideto theEGA and VGA Cards, Second Edition, by Richard Ferraro. 

AUTHOR 


David E. W exablat (dwex@xfrees6.org) with help from D avid D awes (dawese@xfree86.org) and the XFree86 development 
team. 
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tac 


tac— Concatenate and print files in reverse 


SYNOPSIS 
tac [-br] [-s separator] [--before] [--regex] [--separator=separator ] 
[--help] [--version] [file...] 

DESCRIPTION 


This manual page documents the GN U version of tac. tac copies each given file, or the standard input if none are given or 
whe afilenameof - is encountered, to the standard output with the order of the records reversed. T he records are separated 
by instances of a string, or anewline if noneis given. By default, the separator string is attached to the end of the record that 
it follows in the file. 
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OPTIONS 
-b, --before T he separator is attached to the beginning of the record that it precedes in the file 
-r, --regex The separator is a regular expression. 
-s string, --Separator=string Usest ring asthe record separator. 
--help Print a usage message and exit with a non-zero status. 
--version Print version information on standard output, then exit. 


tail 
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tai1— Output the last part of files 


SYNOPSIS 
tail [-c [+]N[bkm]] [-n [+]N] [-fqv] [--bytes=[+]N[bkm]] [--lines=[+]N] 
[--follow] [--quiet] [--silent] [--verbose] [--help] [--version] [file...] 


tail [{-,+}Nbcfklmqv] [file...] 


DESCRIPTION 


This manual page documents the GN U version of tail. tail prints the last part (10 lines by default) of each given file; it 
reads from standard input if no files are given or when afilename of - is encountered. If more than onefileis given, it prints 
a header consisting of the file's name enclosed in ==> and <== before the output for each file 


TheGNU tail can output any amount of data, unlike the UNIX version, which uses a fixed size buffer. It has no -r option 
(print in reverse). Reversing a file is really a different job from printing the end of afile, the BSD taii can only revese files 
that are at most as large as its buffer, which istypically 32KB.A reliable and more versatile way to reverse files isthe GN U 


tac command. 


OPTIONS 


tail accepts two option formats: the new one, in which numbe’s are arguments to the option letters, and theold one in 
which a+r - and optional number precede any option letters. 


If anumber (N) starts with a+, tail begins printing with thenth item from the start of each file, instead of from the end. 


-c N, --bytes N 


-f, -- follow 


-1, -n N, --lines N 
-q, --quiet, --silent 
-v, --verbose 
--help 


--version 


Tail by n bytes. N isanon-zero integer, optionally followed by one of the following characters to 
specify a different unit. 


b 512-byte blocks 

k 1-kilobyte blocks 

m 1-megabyte blocks 

Loop forever, trying to read more characters at the end of the file, on the assumption that the file 
is growing. | gnored if reading from apipe If more than onefile is given, tail prints a header 
whenever it gets output from adifferent file to indicate which file that output is from. 

Tail by n lines. -1 is only recognized using the old option format. 

N ever print filename headers. 

Always print filename headers. 

Print a usage message and exit with a non-zero status. 

Print version information on standard output then exit. 
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talk 


talk 


talk—T alk to another user 


SYNOPSIS 


talk person [ttyname] 


DESCRIPTION 
talk iSa visual communication program that copies lines from your terminal to that of another user. 
The following options are available: 


person If you wish to talk to someone on your own machine, then person is just the person’s login name. If you 
wish to talk to auser on another host, then person is of the form user @host. 

ttyname If you wish to talk to auser who islogged in more than once, thet t yname argument may be used to 
indicate the appropriate terminal name, wherett yname is of the form 
ttyxx 


When first called, talk sends the message Message from TalkDaemon@his_machine...: 


talk: connection requested by your_name@your_machine 
talk: respond with: talk your_name@your_machine 


to the user you wish to talk to. At this point, the recipient of the message should reply by typing 


talk your_name@your_machi ne 


It doesn’t matter from which machine the recipient replies, as long as his login nameis the same. O nce communication is 
established, the two parties may type simultaneously, with ther output appearing in separate windows. Typing control-L 
~ _ will cause the screen to be reprinted, while your erase, kill, and word kil1 characters will behave normally. To exit, 
just type your interrupt character; talk then moves the cursor to the bottom of the screen and restores the terminal to its 
previous state, 


Permission to talk may be denied or granted by use of the mesg 1 command. At the outset, talking is allowed. Certain 
commands, in particular nroff 1 and pr 1, disallow messages in order to prevent messy output. 


FILES 
/etc/hosts To find the recipient’s machine 
/var/run/utmp 70 find therecipient’s tty 

SEE ALSO 
mail(1), mesg(1), who(1), write(1) 

BUGS 


The version of talk 1 rdeased with BSD 4.3 uses a protocol that isincompatible with the protocol used in the version 
released with BSD 4.2. 


HISTORY 
The talk command appeared in BSD 4.2. 


BSD 4.2, 22 April 1991 
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tcal 


tcal— Runs the geal program with the date of tomorrow's day 


SYNOPSIS 


tcal [ --help | --version ] | [ --shift=[+|-]number ][Argument... ] 


DESCRIPTION 


tcal iS a program that runs gcal with a date set one day ahead (equivalent to the - -shift=1 option). All given arguments 
are passed unmodified to the gcal program. If the gcai program shall be called with a date other than tomorrow’s date, this 
desired date can be selected by using the - -shift=[+!-]number option, in which [+!-j]number isthe number of days the 
desired date is distant from the actual date. The - - shift option must be given before all other arguments, which are passed 
to the gcal program. An exit status of @ means all processing is successfully done; any other value means an error has 


occurred. 
OPTIONS 
--help Print a usage message listing all available options, then exit successfully. 
--version Print the version number, then exit successfully. 
--shift=[+!-]number Definethe displacement in [+!-jnumber daysthe desired date is distant from the actual date. 
ENVIRONMENT 
GCALPROG The Gcacproe environment variable contains the filename of the executable gcal program, which 
is used by tcal to call gcai. T akes precedence over the filename gcai, which is burned-in during 
the compilation step of tcal. 
COPYRIGHT 


Copyright© 1995, 1996 by Thomas Esken. T his software doesn’t claim completeness, correctness, or usability. On principle, 
| will not be liablefor any damages or losses (implicit or explicit), which result from using or handling my software. If you 
use this software, you agree without any exception to this agreement, which binds you LEGALLY. 


tcal is free software and distributed under the teams of the GNU General Public License published by the Free Software 
Foundation; version 2 or (at your option) any later version. 


Any suggestions, improvements, extensions, bug reports, donations, proposals for contract work, and so forth are wdcomel! If 
you like this tool, |’d appreciate a postcard from you! 
Enjoy it =8°) 

AUTHOR 


Thomas Esken (esken@uni-muenster.de) 
m H agenfdd 84 

D-48147 M unste; Germany 

Phone: +49 251 232585 


SEE ALSO 
gcal(1) 
16 July 1996 
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telnet 


telnet— User interfaceto theT elne protocol 


SYNOPSIS 


telnet [-d] [-a] [-n tracefile] [-e escapechar] [[-1 user] host [port]] 


DESCRIPTION 


The telnet command is used to communicate with another host using the T elnet protocol. If te1net isinvoked without the 
host argument, it enters command mode, indicated by its prompt telnet>. In thismode, it accepts and executes the 
commands listed bdow. If it isinvoked with arguments, it performs an open command with those arguments. 


OPTIONS 

-d Sets the initial value of the debug toggle to True. 

-a Attempt automatic login. Currently, this sends the username via the user variable of the ENVIRON 
option if supported by the remote system. The name used is that of the current user as returned 
by getlogin 2 if it agrees with the current user ID; otherwise it isthe name associated with the 
user ID. 

-n tracefile Opens tracefile for recording trace information. Seethe set tracefile command in the 
“Commands” section. 

-1 user W hen connecting to the remote system, if the remote systen understands the environ option, then 
user will be sent to the remote system as the value for the variable user. T his option implies the -a 
option. This option may also be used with the open command. 

-e escape char Sdts the initial telnet escape character to escape char. If escape char is omitted, then there will 
be no escape character. 

host Indicates the official name, an alias, or the Internet address of aremote host. 

port Indicates a port number (address of an application). If a number is not specified, the default teinet 
port is used. 


Onceaconnection has been opened, te1net will attempt to enable the TELNETLINEMoDE option. If this fails, then te1net will 
revert to one of two input modes— either character-at-a-time or old line-by-line depending on what the remote system 
supports. 


W hen LINEMmopE is enabled, character processing is done on the local system, under the control of the renote system. W hen 
input editing or character echoing is to be disabled, the renote system will relay that information. The remote systen will 
also relay changes to any special characters that happen on the remote system, so that they can take effect on the local systen. 


In character-at-a-time mode, most text typed is immediately sent to the renote host for processing. 


In old line-by-line mode, all text is echoed locally, and (normally) only completed lines are sent to the renote host. T he local 
echo character (initially *e) may be used to turn off and on the local echo. (T his would mostly be used to enter passwords 
without the password being echoed.) 


If the LINEmoDE option is enabled, or if the 1ocalchars toggle is True (the default for old line by-line), the user’s quit, intr, 
and f1ush characters are trapped locally, and sent as T elnet protocol sequences to the remote side. If LINEmoDE has ever been 
enabled, then the user's susp and eof are also sent as T elnet protocol sequences, and quit is sent aS a TELNET ABORT instead 
of BREAK T here are options (See toggle autoflush and toggle autosynch in the following list) that cause this action to 
flush subsequent output terminal (until the ranote host acknowledges the telnet sequence) and flush previous teminal 
input (in thecase of quit and intr). 
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COMMANDS 


W hile connected to a remote host, telnet command mode may be entered by typing the telnet escape character (initially 
1). When in command mode, thenormal terminal editing conventions are available. 


The following telnet commands are available. O nly enough of each command to uniquely identify it need be typed. (This 
is also true for arguments to the mode, set, toggle, unset, slc, environ, and display commands.) 


close 
display argument... 
mode type 


open host 
user] [-port ] 


quit 


send arguments 


Closea telnet session and return to command mode. 
Displays all, or some, of the set and toggle values. 


type isoneof several options, depending on the state of the telnet session. T he remote host is 
asked for permission to go into the requested mode. If the remote host is capable of entering that 
mode, the requested mode will be entered. Thet ype options are 








character Disable the TELNET LINEMODE option, or, if the renote side does not 
understand the LINEmobDE option, then enter character at a time mode 

line Enable the TELNET LINEMODE option, or, if the remote side does not 
understand the LINEmobE option, then attempt to enter old-line by-line 
mode 

isig -isig Attempt to enable (disable) the Trars1a mode of the LINEmoDE option. This 
requires that the LINEMoDE option be enabled. 

edit -edit Attempt to enable (disable) the Ep1T mode of the LINEmopeE option. T his 
requires that the LINEMoDE option be enabled. 

softtabs Attempt to enable (disable) the sort_TAB mode of the LInNEmopE option. T his 
requires that -softtabs the LINEmopE option be enabled. 

litecho -litecho Attempt to enable (disable) the L1T_EcHo mode of the LIneEmopE option. T his 


requires that the LINEMoDE option be enabled. 
? Prints out hap information for the mode command. 


Open aconnection to the named host. If no port number is specified, te1net will attempt to [ -1 
contact aT elnet server at the default port. The host specification may be ather a hostname (see 
hosts (5)for moreinformation) or an Internet address specified in the dot notation (see inet(3) for 
more information). The -1 option may be used to specify the username to be passed to theremote 
system via the Environ option. W hen connecting to anonstandard port, telnet omits any 
automatic initiation of telnet options. When the port number is preceded by a minus sign, the 
initial option negotiation is done After establishing a connection, thefile in the user’s home 
directory is opened. Lines beginning with a# are comment lines. Blank lines are ignored. Lines that 
begin without whitespace are the start of a machine entry. The first thing on thelineisthe name of 
the machine that is being connected to. The rest of the line, and successive lines that begin with 
whitespace, are assumed to be telnet commands and are processed as if they had been typed in 
manually to the telnet command prompt. 


Close any open telnet session and exit telnet. An end-of-file (in command mode) will also closea 
session and exit. 

Sends one or more special character sequences to the remote host. T he following are the arguments 
that may be specified (more than one argument may be specified at a time): 


abort Sends the TELNET ABorT (Abort Processes) sequence. 

ao Sends the TELNET Ao (Abort Output) sequence, which should cause the 
remote system to flush all output from the remote system to the user’s 
terminal. 

ayt Sends the TELNET AyT (Are You There) sequence, to which the remote 
system may or may not choose to respond. 

brk Sends the TELNET BRK (Break) sequence, which may have significance to the 


remote system. 
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ec Sends the TELNET Ec (Erase Character) sequence, which should cause the 
remote system to erase the last character entered. 

el Sends the TELNET EL (Erase Line) sequence, which should cause the renote 
system to erase the line currently being entered. 

eof Sends the TELNET EoF (End-of-File) sequence 

eor Sends the TELNET Eor (End of Record) sequence. 

escape Sends the current telnet escape character (initially *). 

ga Sends the TELNET GA (Go Ahead) sequence, which likey has no significance 
to the remote systen. 

getstatus If the remote side supports the TELNET STATUS Command, getstatus will 
send the subnegotiation to request that the server send its current option 
status. 

ip Sends the TELNET 1p (Interrupt Process) sequence, which should cause the 
remote system to abort the currently running process. 

nop Sends the TELNET Nop (no operation) sequence. 

susp Sends the TELNET susp (Suspend process) sequence. 

synch Sends the TELNET SYNCH sequence. T his sequence causes the remote system 


to discard all previously typed (but not ye read) input. T his sequence is sent 
as TcP urgent data (and may not work if the remote system isaBSD 4.2 
system— if it doesn’t work, a lowercase r may be echoed on the terminal). 

? Prints out heap information for the send command. 

set argument value, Th@set command will se any one of anumbe of telnet variables to a specific value or to True. 
unset argument value The special value off turns off the function associated with the variable; this is equivalent to using 

the unset command. The unset command will disable or set to False any of the specified 

functions. The values of variables may be interrogated with the display command. The variables 

that may be set or unset, but not toggled, are listed here. In addition, any of the variables for the 

toggle command may be explicitly set or unset using the set and unset commands. 

echo This is the value (initially *e) which, when in line-by-line mode, toggles 
between doing local echoing of entered characters (for normal processing), 
and suppressing echoing of entered characters (for entering, say, a password). 

eof If telnet is operating in LINEmopE or old line-by-line mode, entering this 
character as the first character on aline will cause this character to be sent to 
the remote system. T heinitial value of the eof character istaken to be the 
terminal's eof character. 

erase If telnet isin localchars Mode (See toggle localchars, following), and if 
telnet is operating in character at atime mode, then when this character is 
typed, a TELNET Ec sequence (see send ec, earlier in this man page) is sent to 
the remote system. T heinitial value for the erase character is taken to be the 
terminal's erase character. 


escape This is the te1net escape character (initially *[{) which causes entry into 
telnet command mode (when connected to a remote system). 
flushoutput If telnet iSiN localchars mode (See toggle localchars) and the 


flushoutput character is typed, a TELNET Ao sequence is sent to the ranote 
host. The initial value for the flush character is taken to be the terminal’s 
flush character. 

interrupt If telnet iSiN localchars Mode (See toggle localchars) and the interrupt 
character is typed, a TELNET TuP sequence is sent to the remote host. The 
initial value for the interrupt character is taken to be theterminal’s intr 
character. 
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slc state 


kill 


1Inext 


quit 


If telnet 
operating 


TELNET EL 


iSin localchars mode (see togg 


le localchars), and if telnet is 


in character at a time mode, then when this character is typed, a 
sequence is sent to the remote system. T he initial value for the 


kill character is taken to be the terminal's ki11 character. 


If telnet 
character 
the 1next 


If telnet 


s taken to be the taminal’s inex 
character istaken to be the tem 


iSin localchars mode (see togg 





is operating in LINEMoDE or old li 


ne-by-line mode, then this 
t character. The initial value for 
inal’s inext character. 


le localchars) and the quit 


character is typed, aTELNET BRK Sequence is sent to the remote host. The 
initial value for the quit character is taken to be the terminal’s quit 
character. 

reprint If telnet is operating in LINEmopE or old line-by-line mode, then this 
character is taken to be the terminal's reprint character. The initial value for 
the reprint character is taken to be the taminal’s reprint character. 

start If the TELNETTOGGLE -FLOW-CONTROL option hasbeen enabled, then this 
character is taken to be the taminal’s start character. The initial value for 
the start character istaken to be the terminal's start character. 

stop If the TELNETTOGGLE - FLOW- CONTROL option has been enabled, then this 
character is taken to be the teminal’s stop character. Theinitial value for the 
kill character is taken to be the terminal's stop character. 


susp If telnet iSiN localchars mode, Or LINEMODE is enabled, and the suspend 
character is typed, a TELNET susp sequence is sent to theremote host. The 
initial value for the suspend character is taken to be the terminal's suspend 
character. 


This is the file to which the output, caused by netdata or option tracing 
being True, will be written. If it is set to -, then tracing information will be 
written to standard output (the default). 

If telnet is operating in LINEmopE or old line-by-line mode, then this 
character is taken to be the taminal’s worderase character. The initial value 
for the worderase character is taken to be the terminal’s worderase 
character. 

? Displaysthe set unset commands. 


The sic command (Set Local Characters) is used to set or change the state of the special characters 
when the TELNETLINEMODE option has been enabled. Special characters are characters that get 
mapped to telnet command sequences (like ip or quit) or line editing characters (like erase and 
kill). By default, the local special characters are exported. T he variables are 














tracefile 


worderase 


export Switch to the local defaults for the special characters. T he local default 
characters are those of the local terminal at the time te1net was started. 
import Switch to the remote defaults for the special characters. T he remote default 


characters are those of the remote system at the time when the telnet 
connection was established. 

check Verify the current settings for the current special characters. The renote side 
iS requested to send all the current special character settings, and if thereare 
any discrepancies with the local side, the local side will switch to the remote 
value. 


? Prints out hap information for the sic command. 


environ arguments... 


toggle arguments... 
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The environ command is used to manipulate the variables that may be sent through the TELNET 

ENVIRON option. T he initial set of variables istaken from the users environment, with only the 

DISPLAY and PRINTER Variables being exported by default. Theuser variable is also exported if the 

-a or -1 options are used. 

Valid arguments for the environ command are 

define variable value | Definethevariablevari abi e to havea value of val ue. Any variables 
defined by this command are automatically exported. T he value may 
be enclosed in single or double quotes so that tabs and spaces may be 


included. 

undefine variable Removevari able from the list of environment variables. 

export variable Mark the variable vari abi e to be exported to the remote side. 

unexport variable M ark the variable vari ab! e to not be exported unless explicitly asked 
for by the remote side. 

list List the current set of environment variables. Those marked with a 
will be sent automatically; other variables will only be sent if explicitly 
requested. 

2 Prints out hap information for the environ command. 


Toggle (between True and False ) various flags that control how telnet responds to events. T hese 
flags may be set explicitly to True or False using the set and unset commands listed earlier. M ore 
than one argument may be specified. T he state of these flags may be interrogated with the display 
command. Valid arguments are 


autoflush If autoflush and localchars are both True, then when the ao or 
quit characters are recognized (and transformed into telnet 
sequences; see set for details), telnet refuses to display any data on 
the user's terminal until the remote system acknowledges (viaa 
TELNET TIMING MARK Option) that it has processed those telnet 
sequences. T he initial value for this toggle is True if the terminal user 
had not donean “stty nofish”; otherwiss, False. (See stty(1) for 
more details.) 

autosynch If autosynch and localchars are both True, then when either the 
intr Or quit character is typed (see set for descriptions of the intr 
and quit characters), the resulting telnet sequence sant is followed by 
the TELNET SYNCH sequence This procedure should cause the renote 
system to begin throwing away all previously typed input until both 
of the telnet sequences have been read and acted upon. T he initial 
value of this toggle is False. 





binary Enable or disable the TELNET BINARY option on both input and 
output. 

inbinary Enable or disable the TELNET BINARY option on input. 

outbinary Enable or disable the TELNET BINARY option on output. 

crlf If this is True, then carriage returns will be sent as <cr><LF>. If this is 
False, then carriage returns will be sent as <cr><NuL>. T he initial 
value for this toggle iS False. 

ermod Toggle carriage return mode. When this modeis abled, most 


carriage return characters received from the remote host will be 
mapped into acarriage return followed by a line feed. T his mode does 
not affect those characters typed by the user, only those received from 
the remote host. This mode is not very useful unless the remote host 
only sends carriage return, but never line feed. T he initial value for 
this toggle is False. 
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debug 


localchars 


netdata 


options 


prettydump 


? 


Toggles socket level debugging (useful only to the super user). The 
initial value for this toggle iSFalse. 

If thisis True, then the flush, interrupt, quit, erase, and kill 
characters (see set) are recognized locally, and transformed into 
(hopefully) appropriate telnet control sequences (respectively ao, ip, 
brk, ec, and el; S@ send). T he initial value for this toggle is True in 
old line by-line mode, and False in character at a time mode When 
the LINEMoDE option is enabled, the value of localchars isignored, 
and assumed to always be True. If LINEMODE has ever been enabled, 
then quit is sent as abort, and eof and suspend aresent as eof and 
susp; S€€ send. 

T oggles the display of all network data (in hexadecimal format). The 
initial value for this toggle is False. 

Toggles the display of some internal telnet protocol processing 
(having to do with teinet options). The initial value for this toggle is 
False 

When the netdata toggle is abled, if prettydump is enabled, the 
output from the netdata command will be formatted in amore user- 
readable format. Spaces are put between each character in the output, 
and the beginning of any te1net escape sequence is preceded by an * 
to aid in locating them. 


Displays the legal toggle commands. 


z Suspend telnet. T hiscommand only works when the user is using the csh(1). 


! command Execute a single command in a subshdl on the local system. If command isomitted, then an 
interactive subshell is invoked. 


status Show the current status of teinet. This includes the peer oneis connected to, as wel as the current 


mode. 


2 command Get help. With no arguments, te1net printsahdp summary. If acommand is specified, telnet 
will print the help information for just that command. 


ENVIRONMENT 


telnet uses at least the HOME, SHELL, DISPLAY, and TERM environment variables. O ther environment variables may be 
propagated to the other side via the TELNET ENVIRON option. 


FILES 


~/.telnetre User customized telnet startup values 


HISTORY 


The telnet command appeared in BSD 4.2. 


NOTES 


On someremote systems, echo has to be turned off manually when in old line by-line mode. 


In old line-by-line mode or LINEmobE, the teminal’s eof character is only recognized (and sent to the remote system) when it 


is the first character on aline 


BSD 4.2, 27 July1991 
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tfmtodit 


tfmtodit— Create font files for use with groff -Tdvi 


SYNOPSIS 


tfmtodit [ -sv ][-ggf file ][-kskewchar ] tfm file map file font 


DESCRIPTION 


tfmtodit creates a font file for usewith groff -Tdvi. tfm_file isthename of the font metric file for thefont. map_file isa 
file giving the groff names for characters in the font; this file should consist of a sequence of lines of the form: 





n cic2 ... 


where n isa decimal integer giving the position of the character in the font, andc1, c2,... arethe grorf names of the 
character. If a character has no groff names but exists in the tfm file then it will be put in the gro font file as an unnamed 
character. font isthe name of the groff font file. The groff font file is written to font. 


The -s option should be given if the font is special (a font is special if trot should search it whenever a character is not 
found in the current font.) If the font is special, it should be listed in the fonts command in thevesc file; if it isnot special, 
there isno need to list it because troff can automatically mount it when it’s first used. 


To do a good job of math typesetting, grofF requires font metric information not present in the tm file. The reason for this 
is that has separate math italic fonts whereas groff uses norma italic fonts for math. The additional information required by 
groff is given by the two arguments to the math_fit macro in the M etafont programs for the Computer M odern fonts. In a 
text font (afont for which math_fitting iS False), M etafont normally ignores these two arguments. M etafont can be made 
to put this information in the gf file by loading the following definition after cmbase when creating cm. base: 





def ignore_math_fit(expr left_adjustment,right_adjustment) = 
special "adjustment"; 

numspecial left_adjustment*16/designsize; 

numspecial right_adjustment*16/designsize; 

enddef; 


The gf file created using this modified cm.base should be specified with the -g option. The -g option should not be given 
for afont for which math_fitting istrue. 


OPTIONS 
“Vv Print the version number. 
“8 The font is special. T he effect of this option is to add the special command to the font file 
-kn The skewchar of this font is at position n. n should be an integer; it may be given in decimal, or with a 


leading o in octal, or with a leading ox in hexadecimal. The effect of this option is to ignore any kerns 
whose second component is the specified character. 

-ggf_file gf _file iSag¢ file produced by M etafont containing special and num special commands giving additional 
font metric information. 


FILES 
/usr/lib/groff/font/devdvi/DEsc Devicedescription file 
/usr/lib/groff/font/devdvi/F Font description file for font F. 
SEE ALSO 


groff(1), grodvi(1), groff_font(5) 
Groff Verson 1.09, 14 February 1994 
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tftp— Trivial file transfer program 


SYNOPSIS 


tftp [host ] 


DESCRIPTION 


tftp istheuser interface to the Internet TFTP (Trivial File Transfer Protocol), which allows users to transfer files to and from 
a remote machine. T he remote host may be specified on the command line, in which case tftp uSeShost asthe default host 
for future transfers. (See the connect command in the following section.) 


COMMANDS 


Once tftp isrunning, it issues the prompt: 


tftp> 


and recognizes the following commands: 


? command-name ... 
ascii 
binary 


connect host-name port 


get filename, 
get remotename localname, 


get file1 file2 ... fileNn 
mode transfer-mode 

put file 

put localfile remotefile 


put filel file2.. 
fileN remote- directory 


quit 

rexmt 
retransmission-timeout 
status 


timeout 
total-transmission-ti meout 


trace 


verbose 


BUGS 


Print help information. 
Shorthand for “mode ascii” 
Shorthand for “mode binary” 


Sa thehost (and optionally port ) for transfers. N ote that the T FTP protocol, unlike the 
FTP protocol, does not maintain connections between transfers; thus, the connect 
command does not actually create a connection, but merdy remenbers what host is to be 
used for transfers. You do not have to use the connect command; the remote host can be 
specified as part of the get or put commands. 


Get afileor set of files from the specified sources. Source can bein one of two forms: a 
filename on the remote host, if the host has already been specified; or a string of the form 
hosts:filename to specify both a host and filename at the same time If the latter form is 
used, the last hostname specified becomes the default for future transfers. 


Se the mode for transfers; transfer- mode May be ascii Or binary. The default is ascii. 


Put a file or set of files to the specified remote file or directory. T he destination can be 
in one of two forms: a filename on the remote host, if the host has already been specified; 
or astring of the form hosts:filename to specify both ahost and filename at the sane 
time. If the latterform is used, the hostname specified becomes the default for future 
transfers. If the remote -directory form is used, the remote host is assumed to bea 
UNIX machine. 


Exit tftp . An end-of-filealso exits. 
Set the pe-packet retransmission time-out, in seconds. 


Show current status. 
Se the total transmission time-out, in seconds. 


T oggle packet tracing. 
Toggle verbose mode 


Because there is no user-login or validation within the T FTP protocol, the remote site will probably have some sort of file 
access restrictions in place. The exact methods are specific to each site and therefore difficult to document here. 
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BSD 4.3, 22 April 1991 


HISTORY 
The tftp command appeared in BSD 4.3. 
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tgatoppm— Convet TrueVision T arga file into a portable pixmap 


SYNOPSIS 

tgatoppm [-debug][tgafile] 
DESCRIPTION 

Reads aT rueVision Targa file as input. Produces a portable pixmap as output. 
OPTIONS 


-debug Causes the header information to be dumped to stderr 
All flags can be abbreviated to their shortest unique prefix. 
BUGS 


Should really bein pnm, not ppm. 
SEE ALSO 
ppmtotga(1), ppm(5) 
AUTHOR 
Partially based on tga2rast, version 1.0, by lan J. M acPhedran 
Copyright© 1989 by J ef Poskanzer. 
26 August 1989 
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tifftopnm— Convert aTIFF file into a portable anymap 


SYNOPSIS 


tifftopnm [-headerdump] tifffile 


DESCRIPTION 


tifftopnm reads aTIFF file as input and produces a portable anymap as output. T he type of the output file denends on the 
input file if it’s black and white, a pbm fileis written;, if it’s grayscale, a pgm file otherwise, a ppm file. T he program tells you 
which type it is writing. 


OPTIONS 


-headerdump Dump TIFF file information to stderr. T his information may be useful in debugging TIFF file 
conversion problems. 


All flags can be abbreviated to their shortest unique prefix. 
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SEE ALSO 


pnmtotiff(1), pnm(5) 


BUGS 
This program is not self-contained. To use it you must fetch the TIFF Software package listed in the oTHER. SYSTEMS file and 
configure pbmp1us to use 1ibtitf. See the pbmplus Makefile for details on this configuration. 

AUTHOR 
Derived by Jef Poskanzer from tif2ras.c, which is copyright© 1990 by Sun M icrosystens, Inc. Author Patrick J. Naughton 


(naughton@wind.sun.com), 


13 January 1991 


tin, rtin, cdtin, tind 
tin, rtin, cdtin, tind—A N etnews reader 


SYNOPSIS 


tin/rtin/cdtin/tind [ options ][newsgroups ] 


DESCRIPTION 


tin isa full-screen easy-to-use N etnews reader. It can read news locally (/usr/spool/news) or remotely (rtinortin -r 
option) viaan N NTP (Network N ews Transport Protocol) server. cdtin can read news locally and news archived on CD- 
ROM. It will automatically utilize nov (news overview)-style index files if available locally or via the nntp xover command. 


tin has five separate levels of operation: group selection leva, spooldir selection level, group level, thread level and article 
level. Use the h (hap) command to view alist of the commands available at a particular level. 


On startup, tin will show a list of the newsgroups found in $HomE/.newsre. An arrow -> or highlighted bar will point to the 
first newsgroup. M ove to a group by using the terminal arrow keys (terminal-dependent) or j and k. Use PgU p/PgD n 
(terminal-dependent) or Ctrl-U and Ctrl-D to page up/down. Enter a newsgroup by pressing Return. 


TheT ab key advances to the next newsgroup with unread articles and enters it. 


OPTIONS 

-C Create/update index files for every group in $HOME/.newsrc or file specified by -¢ option and mark all 
articles as read. 

f file Use the specified file of subscribed to newsgroups in place of $HOME/.newsrc. 

-h H elp listing all command-line options. 

H Brief introduction to tin that is also shown the first time it is started. 

I dir Directory in which to store newsgroup index files. D efault is $HOME/.tin/.index. 

-m dit M ailbox directory to use. D efault is $HOME /Mail. 

-M user M ail unread articles to specified user for later reading. For more information read the “Automatic M ailing 
and Saving N ew N ews” section later in this manual page. 

-n Only load groups from the active file that are also subscribed to in the users .newsrc. This allows a 
noticeable speedup when connecting via a slow line. 

-p program Print program with options. 

-q Quick start without checking for new newsgroups. 





Purge group index files of articles that no longer exist. Care should be taken when using this command as 
it starts each and every article in each group that is accessed. On a low-speed connection, this can have an 
undesirable effect and it also knocksthehell out of your filesysten. 
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-r Read news renotely from the default N N TP server specified in the environment variable NNTPSERVER OF 
contained in the file /etc/nntpserver. 

-R Read news saved by -s option (not yet implemented). 

-s dir Save articles to directory. D efault is $HomeE /News. 

-S Save unread articles for later reading by -r option. For more information, see “Automatic M ailing and 
Saving N ew N ews.” 

-u Create/update index files for every group in $HOME/.newsrc or file specified by - option. T his option is 
disabled if tin retrieves its index files viaan NNTP server. 

-U Start tin in the background to update index files while reading news in the foreground. T his option is 
disabled if tin retrieves its index files viaan NNTP server. 

“Vv Verbose mode for -c, -m, -S, -u, and -z options. 

Ww Quick mode to post an article and then exit. 

-Z Only start tin if there is any new/unread news. If thereis news, tin will position cursor at first group with 
unread news. Useful for putting in login file. 

-Z Check if there is any new/unread news and exit with appropriate status. If -v option is specified, the 


number of unread articles in each group is printed. An exit code a indicates no news, 1 that an error 
occurred, and 2 that new/unread news exists. U seful for writing scripts. 


tin can also dynamically change its options by them menu command. Any changes are written to $HOME/.tin/tinrc. 
The index daemon version, tind, only supports the -f, -h, -1, and -v options. 


IND EX FILES 


In order to keep track of threads, tin maintains an index for each newsgroup. T here are anumber of methods in which 
index files can be created and updated. 


Thesimplest method is that each user creates/updates his or her own index files that are stored in $HOME/.tin/.index. This 
has the advantage that any user can compile and install tin, but the disadvantage is that each user is going to be creating 
duplicate files and using precious disk space. A good way to keep index files updated is by doing atin -u that will update 
index files in the background while you are reading news in the foreground. You can also update index files via the systen 
batcher cron with the -u option: 30 6 ***/usr/local/bin/tin -u. 


A slightly better method is to set tin setuid news and haveall index files created and updated in the news spool directory 
(that is, /usr/spool/news/ .index). This has the advantage that there will only be one copy of the index files on each 
machine on your network, but the disadvantage is that you will have tin running setuid news. 


A better method is to install the tind index file updating daemon and haveit create and update index files for all groupsin 
your active file at regular intervals in the news spool directory (/usr/spool/news/ . index). T his has the advantage that there 
will only be one copy of the index files on each machine on your network, and tin must not be setuid news, but the 
disadvantage is that you will have to have news permissions to install tina and root permissions to install an entry in the 
cron batcher system to have tind regularly update index files. 


The best method is to install the tina index file updating daemon on your NNTP server and have it create and update index 
files for all groups in your active file at regular intervals in thenews spool directory (/usr/spool/news/. index). Thishasthe 
advantage that there will only be one copy of the index files on the N N TP server for the whole of your network, but the 
disadvantage is that you will have to install my N NTP server patches to allow tin to retrieve index file from your NNTP 
server and you must install an entry in the cron batcher systen to have tind regularly update index files. (T his is the method 
we use on our network of 40 to 50 machines and we have not had any problems.) 





Entering agroup the first time tends to be sow because the index file must be built from scratch unless the ting update 
daemon is being used. To alleviate the slowness, start tin to create all index files for the groups you subscribe to with 
tin -u -v and go for acoffee. Subsequent readings of a group will cause incremental updating of the index file 
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If reading news remotely and locally updating index files operation will be somewhat slower because the articles must be 
retrieved from the NNTP server. 


NEWS ADMINISTRATION 


M aintaining N etnews on large networks of machines can be a pretty time-consuming job, as! discovered when | was given 
the job of maintaining our news system and news users. 


tin isaN ews User Agent and so most of the users were always asking questions or doing things that could be frowned upon 
by ther departments. To relieve news administrators (and especially me) of this, features have been added to make life easier 
for them. 


W hen auser starts tin, it is possible to inform them of any important changes or information concerning the news system by 
displaying a message of the day (motd) file T he mota file should be created in your news lib directory (/usr/1ib/news/motd) 
and should have file permissions set to 644. T he mot file will only be displayed if its contents is newer than the last time 
the user started tin. If reading news viaN NTP, my xmotp patch will have to have ben applied to your NNTP serve. 


A user starting tin for the first time can be automatically subscribed to a list of newsgroups that are deemed appropriate by 
the news administrator. At our site the subscriptions file has 125 groups (our active file contains more than 400 groups with 
many only being marginally interesting to most people). The subscriptions file should be created in your news lib directory 
(/usr/1ib/news/subscriptions) and should have file permissions set to 0644. If reading news viaNNTP, my LIst 
SUBSCRIPTIONS patch will have to have been applied to your NNTP server. 


If my NNTP xuser patch has been applied to your NNTP server, you will be able to log the username and machine to your 
NNTP logfile for usage statistics. 
SCREEN FORMAT 


tin has five separate levels of operation: group selection levd, spooldir selection level, group level, thread level, and article 
leva. 


At the group selection level, the title displays the number of subscribed groups. T he newsgroups are displayed on the left of 
the screen with the number of unread articles displayed on the same linein the middle of the screen, like this: 


<Selection Num><Newsgroup><Num of unread articles> 


i.e., 

1 alt.sources 10 
2 comp.sources.misc 3 
3 news.software.readers 12 


At the group level, the title contains the name of the group, the number of conversation threads, and total number of articles, 
for example, alt.sources (7 23).If the group has been set up not to thread articles (for example, alt.sources isin 
$(HOME) /.tin/unthread), the title will bealt.sources (U 23). There are two possible display formats: 


<Selection Num><Unread><Responses><Subject><Author> 


e.g. 

1 + 3 Bnews sources? iain@anl433.uucp 
2 1 This question has ether@net 
or 
<Selection Num><Unread><Responses><Subject (longer)> 
€.g.,; 

Pook 8 Bnews sources? 

2 1 This question has a longer subject line 


At the article level, the page header has the following format: 


<Date posted><Newsgroup> 
<Thread 1 of n> 
<Article Num><Subject><Num of responses in thread> 


tin, rtin, cdtin, tind 


<Author><Organization> 
<Article body> 


LiBey 

24 Jul 15:20:03 GMT alt.sources Thread 1 of 2 
Article 452 Bnews sources? 3 responses 
iain@an1433.uucp Organization name 


COMMON MOVING KEYS 


The following table shows the common keys/commands for moving at all five levels within tin: 


Beginning of list/article Home 1(*ROrg at article levd) 
End of list/article End $ (also G at article level) 

Page up PgUp “UOr *BOr b 

Page down PgDn “DOr *F Or <SPACE> 
Lineup Up arrow k (not at article level) 
Line down Down arrow j (not at article levd) 


COMMON EDITING COMMANDS 


An emacs -style editing package allows the easy editing of input strings. A history list allows the easy reuse of previously 
entered strings. T he following commands are available when editing a string: 


“A, *E M ove to beginning or end of line, respectively. 

“F,*B N ondestructive move forward or back one location, respectively. 

“D D elete the character currently under the cursor, or send Eor if no characters are in the buffer. 

“H, <DEL> D elete character left of the cursor. 

“K D elete from cursor to end of line 

“P, *N M ove through history, previous and next, respectively. 

“L, oR Redraw the current line 

<CR> Places line on history list if nonblank, appends newline, and returns to the caller. 

<ESC> Aborts the present editing operation. 

NEWSGROUP SELECTION COMMANDS 

4 Sdect group 4. 

“K D elete current group from $HoME/.newsrc file 

ae Redraw page. 

“R Reset $HOME/.newsrc file. 

<CR> Read current group. 

<TAB> View next group with unread news. W ill wrap around to the beginning of the group selection list looking 
for unread groups. 

B M ail a bug report or comment to the author. T his isthe best way to get bugs fixed and features added/ 
changed. 


M ark current group as all read with confirmation and go to next group in group selection list. 
M ark current group as all read and go to next unread group in group selection list. 
Toggle display to show just the group name or the group name and the group’s description. 


Choose anew group by name. T he position of the group within the group list will also be asked for. When 
1 is entered, the new group will be the first group in the displayed list; when 8 is entered, the group will be 
the eighth group in the list; and so on. When ¢ isentered, the group will be the last group displayed. 


Oo oS. 


Part |: User Commands 


ae = =e 


co Nn DM 


< 


< sé 


< 


" ~ NN 


H elp screen of newsgroup selection commands. 
Toggle the display of hap mini-menu at the bottom of the screen. 
T oggle inverse video. 


List and allow selection of the available spool directories. T his feature requires a special library to be linked 
with tin to create cdtin, which can then read news from an active news feed and also from multiple CD - 
ROMs. 


M ove the current group within the group selection list. When 1 isentered, the group will become the first 
displayed group in the list; when g isentered, the eighth group in the list; and so on. When ¢ is entered, 
the group will be the last group displayed. 


User-configurable O ptions menu (for more information, see the “Global O ptions M enu” section later in 
this manual page). 

Quit tin. 

Quit tin. 

T oggle display of all subscribed-to groups and just the subscribed-to groups containing unread articles. 
Command has no effect if groups were read from the command line when tin was started. 

Subscribe to current group. 

Subscribe to groups matching user-specified pattern. 

Unsubscribe to current group. 

Unsubscribe to groups matching user-specified pattern. 

Print tin version information. 

Post an article to current group. 

List articles posted by user. The date posted, the newsgroup, and the subject are listed. 


The first time this command is called, it will yank in all groups from $L1B-DIR/active that arenot in 
$HOME/.newsrc. 


After any groups have bean subscribed/unsubscribed to, this command, if pressed again, will reread $HOME / 
.newsrc and display only the subscribed groups. 


Reread the active file to see if any new news has arrived since starting tin. 
M ark all articles in the current group as unread. 

Unddéte previously deleted group by *k command from $HoME/.newsrc. 
Group forward search. 

Group backward search. 


SPOOL DIRECTORY SELECTION COMMANDS 


Oo 2 


< 


Sdect spool directory 4. 
Redraw page. 
Read news from selected spool directory. 


M ail a bug report or comment to the author. This is the best way to get bugs fixed and features 
added/ changed. 


H elp screen of spool directory sdection commands. 

Toggle the display of hap mini-menu at the bottom of the screen. 
T oggle inverse video. 

Return to previous level. 

Quit tin. 

Print tin version information. 


GROUP INDEX COMMANDS 
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4 Select article 4. 


“K Kill current article (for more information, see the “Automatic Kill and Selection” section later in this 
manual page). 

Ap Redraw page. 

<CR> Read current article. 

<TAB> View next unread article or group. 

Author forward search. 

Author backward search. 

M ark all articles as read with confirmation. 

M ark all articles as read and go to next group with unread news. 

Toggle display to show just the subject or the subject and author. 

Choose anew group by name. 

H elp screen of group index commands. 

Toggle the display of hap mini-menu at the bottom of the screen. 

T oggle inverse video. 

M ark article/thread as read and advance to next unread article/thread. 

List the author of each response in current thread and enter thread selection level. 

M ail current article/thread/auto-selected (hot) articles/articles matching pattern/tagged articles to someone. 

U ser-configurable O ptions menu (for more information see “Global O ptionsM enu” section). 

Go to next group. 

Go to next unread article. 


Output current article/thread/autosel ected (hot) articles/articles matching pattern/tagged articles to 
printer. 

Go to previous group. 

Go to previous unread article 

Return to previous level. 

Quit tin. 

Save current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles to file/files/ 
mailbox. T o save to a mailbox, enter = or =mailbox when asked for filename to save to. To savein 
<newsgroup name>/<filename> format, enter +filename. Environment variables are allowed within a 
filename (for example $souRCES/dir/filename). 


t Tag current article/thread for mailing (m)/piping (|)/printing (o)/saving (s)/crossposting (x). 
u T oggle display to show all articles as unthreaded or threaded. 

Untag all articles that were tagged. 

Print tin version information. 

Post an article to current group. 

List articles posted by user. T he date posted, the newsgroup, and the subject are listed. 


Crosspost already posted current article/thread/autoselected (hot) articles/articles matching pattern/tagged 
articles to another newsgroup(s). U seful for reposting from global to local newsgroups. 


X M ark all unread articles that have not bem sdected as read, redo screen to reflect changes, and put index at 
the first thread to begin reading. Pressing x again will toggle back to the way it was before See ~ command 
for clearing the toggle effect. 


z M ark current article as unread. 
Zz M ark current thread as unread. 
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Search forward for specified subject. 
Search backward for specified subject. 
Show last message. 


Pipe current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles into 
command. 


Sdect current thread for later processing. 


Toggle sdection of current thread. If at least one unread art in thread (but not all unread arts) is selected, 
then all unread arts become selected. 


Reverse all selections on all articles. 

Undo all sdections on all articles. It clears the toggle effect of x command. Thus, after first doing an x, you 
can then do ~ to reset articles. Thus, you can iteratively whittle down uninteresting threads. 

Perform autosdection on current group. 

For each thread in current group, if it at least one unread art is selected, all unread arts become selected. 
This is useful for autosdection on author when the reader wants to see the entire thread. 

Prompts for a pattern with which to match on. All threads whose subjects match the pattern will be 
selected. A pattern of « will match all subjects. Entering just <cr> will cause the previous pattern to be 
used. 


THREAD LISTING COMMANDS 


4 Sdect article 4 within thread. 

aL Redraw page. 

<CR> Read current article within thread. 

<TAB> View next unread article within thread. 

B M ail a bug report or comment to the author. T his isthe best way of getting bugs fixed and features added/ 
changed. 

c M ark thread as read after confirmation and return to previous level. 

d Toggle display to show just the subject or the subject and author. 

h H elp screen of thread listing commands. 

H Toggle the display of hdp mini-menu at the bottom of the screen. 

I T oggle inverse video. 

K M ark thread as read and return to previous levd. 

q Return to previous level. 

Q Quit tin. 

r T oggle display to show all articles or only unread articles. 

B M ail a bug report or comment to the author. T hisis the best way of getting bugs fixed and features added/ 
changed. 

t Tag current article for mailing (m)/piping (|)/printing (0)/saving (s)/crossposting (x). 

T Return to group index level. 

v Print tin version information. 

z M ark current article in thread as unread. 

z M ark all articlesin thread as unread. 

ARTICLE VIEWER COMMANDS 

t) Read the base article in this thread. 

4 Read response 4 in this thread. 

“H Show all of the article's mail header. 
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“K Kill current article (for more information, see the “Automatic Kill and Selection” section) 
aL Redraw page. 

<CR> Go to next base article 

<TAB> Go to next unread article. 

Author forward search. 

Author backward search. 

M ark all articles as read with confirmation and return to group selection level. 

M ark current group as all read and go to next unread group in group selection list. 
Toggle rot-13 decoding for this article 


D elete current article. It must have been posted by the same user. T hecancel message can be seen in the 
newsgroup control. 


Post a follow-up to the current article with a copy of the article included. 

Post a follow-up to the current article. 

H elp screen of article page commands. 

Toggle the display of hdp mini-menu at the bottom of the screen. 

T oggle inverse video. 

M ark article as read and advance to next unread article 

M ark thread as read and advance to next unread thread. 

M ail current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles to someone 
User-configurable O ptions menu (for more information, see the “Global O ptions M enu” section later in 
this manual page). 

n Go to thenext article. 

N Go to the next unread article 


Output current article/thread/autosdected (hot) articles/articles matching pattern/tagged articles to 
printer. 


Output article/thread/tagged articles to printer. 

Go to the previous article 

Go to the previous unread article 

Return to previous level. 

Quit tin. 

Reply through mail to the author of the current article with a copy of the article included. 
Reply through mail to the author of the current article 


s Save current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles to file/files/ 
mailbox. To save to a mailbox enter = or =mailbox when asked for filename to save to. To savein 
<newsgroup name>/<filename> format, enter +filename. Environment variables are allowed within a 
filename (such as $SOURCES/dir/filename). 


t Return to group sdection level. 
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T Tag current article for mailing (m)/piping (!)/printing (0)/saving (s)/crossposting (x). 
v Print tin version information. 

Ww Post an article to current group. 

w List articles posted by user. The date posted, the newsgroup and the subject are listed. 


Crosspost already posted current article/thread/autoselected (hot) articles/articles matching pattern/tagged 
articles to another newsgroup(s). U seful for reposting from global to local newsgroups. 


z M ark article as unread. 
/ Article forward search. 
2 Article backward search 


x 
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Pipe current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles into 


command. 
< Go to thefirst article in the current thread. 
> Go to the last article in the current thread. 
* Sdect current thread for later processing. 
* Toggle sdection of current article. 


@ Reverse article selections. 
: Undo all sections on current thread. 


GLOBAL OPTIONS MENU 


This menu is accessed by pressing m at all levels. It allows the user to customize the behavior of tin. T he options are saved to 
the file $HomE/.tin/tinrc. U Se <space> to toggle the required option and <cr> to set. 


Auto save 
Editor offset 


M ark saved read 
Confirm Command 


D raw arrow 
Print header 


Go to 1st unread 


Scroll full page 
Catch up on quit 


Thread articles 


Show only unread 
Show description 


Show Author 


Process type 


Automatically save articles/threads by “Archivename:” linein article header and post process then 

if process type is not set to None. 

Set on if the editor used for posting, follow-ups and bug reports has the capability of starting and 

positioning the cursor at a specified line within afile 

Allows saved articles/threads to be automatically marked as read. 

Allows certain commands (such aSc catchup) that require user confirmation to be executed 

immediately if set oFF. 

Allows groups/articles to be selected by an arrow -> if set on or by ahighlighted bar if set orF. 

This allows the complete mail header or only the “Subject:” and “From:” fields to be output when 

printing articles. 

This allows the cursor to be placed at the first/last unread article upon entering a newsgroup with 

unread news. 

If set on, scrolling of groups/articles will be a full page at a time otherwise, haf apage at atime 

If set on, the user is asked when quitting if all groups read during the current session should be 

marked read. 

If set on, articles will be threaded in all groups (default); otherwise, articles will be shown 

unthreaded. T hreading or unthreading is possible on a per-group basis by setting the group 

attribute variable thread_arts to on/OFF in the file $HOME/.tin/attributes. 

If set on, show only new/unread articles; otherwise, show all articles. 

If set on, show a short descriptive text for each displayed newsgroup. The text used is taken from 

the $LIBDIR/ newsgroups file. 

If set None, only the “Subject:” line will be displayed. If set adar, “Subject:” line and the address 

part of the “From:” line are displayed. If set Name, “Subject:” line and the author's full name part of 

the “From:” line are displayed. If set Both, “Subject:” line and all of the “From:” line are displayed. 

This specifies the default type of post processing to perform on saved articles. The following types 

of processing are allowed: 

m None 

Unpacking of multipart shell archives 

Unpacking of multipart uuencoded files 

Unpacking of multipart uuencoded files, which produce a * . zoo archive whose contents are 

listed 

Unpacking of multipart uuencoded files, which produce a * . zoo archive whose contents are 

extracted 

m Unpacking of multipart uuencoded files, which produce a * . zip archive whose contents are 
listed 
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m Unpacking of multipart uuencoded files, which produce a *. zip archive whose contents are 
extracted 

m= Unpacking of multipart uuencoded files, which produce an *. 1ha archive whose contents are 
listed (AmigaD O S version only) 

m Unpacking of multipart uuencoded files, which produce an «.1ha archive whose contents is 
extracted (AmigaD OS version only) 


This specifies how articles should be sorted. The following sort types are allowed: 


m Don't sort articles (default). 

m Sort articles by “Subject:” fidd (ascending and descending). 
m Sort articles by “From:” fidd (ascending and descending). 
m Sort articles by “D ate” fidd (ascending and descending). 


The directory where articles/threads are to be saved. D efault is $HOME /News. 


Sort articles by 


Save directory 


M ail directory The directory where articles/threads are to be saved in mailbox format. T his feature is mainly for 
use with the elm mail program. It allows the user to save articles, threads, or groups simply by 
giving = as the filename to save to. 

Printer Theprinter program with options that is to be used to print articles. D efault is 1pr for BSD 


machines and 1p for SysV machines. 


tinrc CONFIGURABLE VARIABLES 


The following variables are user-configurable by editing $HomE/.tin/tinrc directly. It is hoped to eventually provide a menu 
to allow the setting of the most common variables. 


If set on, articles/threads will be saved in batch mode when save -s or mail -m is specified on 
the command line D efault is orF. 

If set on, a mini-menu of the most useful commands will be displayed at the bottom of the 
screen for each level. D efault is on. 

The prompt Reading. .. will be displayed when reading an article from an NNTP server to 
provide feedback to the user. D efault is on. 

Specifies whether a screen redraw should always be done after certain external commands. 

D efault is oFF. 

Maximum length of the names of newsgroups to be displayed so that more of the 
newsgroup description can be displayed. D efault is 132. 

The path that specifies the signature file to use when posting, following up to, or replying to 
an article. If the path is a directory, then the sgnature will be randomly generated from files 
that are in the specified directory. D efault is $HoME/. Sig. 


batch_save 


beginner_level 


display_reading_prompt 


force_screen_redraw 


groupname_max_length 


default_sigfile 


editor_format 


hot_art_mark 


quote_chars 


reread_active_file_secs 


return_art_mark 


save_to_mmdf_mailbox 


show_last_line_prev_page 


The format string used to create the editor start command with parameters. D efault is se 
+%N %F (for example /bin/vi +7 .article). 
The character used to show that an article/thread is autoselected (hot). D efault is*. 


The character used in quoting included text to article follow-ups and mail replies. The: ' 
character represents a blank character and is replaced with ' ' when read. Defaultis': '. 


The news active file is reread at regular intervals to show if any new news has arrived. 
D efault is 300 seconds. 


The character used to show that an article will return. D efault is -. 

Allows articles to be saved to an mmaf-style mailbox instead of mbox format. D efault is oFF 
unless reading news on SCO UNIX, which uses mur by default. 

The last line of the previous page will be displayed as the first line of next page. D efault is 
OFF. 
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slow_speed_terminal Strips the blanks from the end of each line, thereby speeding up the display when reading 
on aslow terminal or via modem. D efault is oFF. 

tab_after_X_selection If enabled, will automatically go to the first unread article after having selected all hot 
articles and threads with the x command at group index leva. D efault is orF. 

tab_goto_next_unread If enabled, pressing T ab at the article viewer level will go to the next unread article 
immediately instead of first paging through the current one D efault is on. 

unread_art_mark The character used to show that an article has not been read. D efault is +. 

use_builtin_inews Allows the built-in NNTP inews to be enabled/disabled. D efault ison (enabled). 

use_keypad Allows the scroll keys on the keypad to be enabled/disabled on supported terminals. D efault 
iS OFF. 

GROUP ATTRIBUTES 


tin allows cetain attributes to be set on aper-group basis. T hese group attributes are read from thefile $HomE/. tin/ 
attributes. A later version will provide a menu interface to set all the attributes. At present, you will have to edit the file 
with your editor :-(. The following group attributes are available: 

newsgroup=alt.sources 

maildir=/usr/iain/Mail/sources 

savedir=/usr/iain/News/alt.sources 

sigfile=/usr/iain/.funny sig 

organization=Wacky Bits Inc. 

followup to=alt.sources.d 

printer=/usr/local/bin/a2ps -nn | /bin/lpr 

auto save=ON 

batch save=OFF 

delete tmp files=0N 

show only unread=OFF 

thread arts=0N 

show author=1 

sort art type=5 

post proc type=1 


N ote that the newsgroup=<groupname> line has to be specified before the attributes are specified for that group. 


All attributes are set to a reasonable default so you only haveto specify the attribute that you want to change (for example, 
savedir). 


All toggle attributes are set by specifying on/OFF. 


The show_author attribute is specified by anumber from the following range: enone 1=username, 2=network address, 
3=poth. 


The sort_art_type attribute is specified by anumber from the following range @=none, 1=Subject descending, 2=subject 
ascending, 3=from descending, 4=from ascending, s=date descending, 6=date ascending. 


The post_proc_type attribute is specified by anumber from the following range: a=none, 1=unshar, 2=uudecode, 
3=uudecode & list zoo archive, 4=uudecode & extract zoo archive, 5=uudecode & list zip archive, e=uudecode & extract zip 
archive. (If running on AmigaD OS, the zoo options are replaced by their corresponding 1ha archiver options.) 


AUTOMATIC KILL AND SELECTION 


W hen there is a subject or an author that you are ther very interested in, or find completely uninteresting, you can easily 
instruct tin to autoselect or autokill articles with specific subjects or from specific authors. T hese instructions are stored in a 
kilt file 


This menu is accessed by pressing *k at the group and page levas. It allows the user to kill or select an article that matches 
the current “Subject:” line, “From:” line or a string entered by the user. T he user-entered string can be applied to the 
“Subject:” or “From:” lines of an article The ki11 description can be limited to the current newsgroup or it can apply to all 
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newsgroups. O nce entered, the user can abort the command and not save the ki11 description, edit the ki11 file or savethe 
kill description. 


On starting tin, theuser’s kill file $HomE/.tin/kil1 is read and on entering a newsgroup any kill or select descriptions 
are applied. 


Articles that match aki11 description are marked killed and are not displayed. Articles that match an autoselect description 
are marked with an * when displayed. 


PO STING ARTICLES 


tin allows posting of articles, follow-up to already posted articles, and replying direct through mail to the author of an 
article 


Use the w command to post an article to a newsgroup. After entering the post subject, the default editor (such asvi) or the 
editor specified by the svisuaL environment variable will be started and the article can be entered. T 0 crosspost articles, 
simply add acomma and the name of the newsgroup(s) to the end of the “N ewsgroups.” line at the beginning of the article. 
After saving and exiting the editor, you are asked if you wish to abort posting the article, edit the article again or post the 
article to the specified newsgroup(s). 


Use thew command to display a history of the articles you have posted. T he date the article was posted, which newsgroups 
the article was posted to, and the article’s subject line are displayed. 


Use the t/F command to post a follow-up article to an already posted article. The ¢ command will copy the text of the 
original articleinto the editor. T he editing procedure is the same as when posting an article with thew command. 





Use the r/R command to reply direct through mail to the author of an already posted article Ther command will copy the 
text of the original article into the editor. T he editing procedure is the same as when posting an article with the w command. 
After saving and exiting the editor, you are asked if you wish to abort sending the article, edit the article again, or send the 
article to the author. 


CUSTOMIZING THE ARTICLE QUOTE STRING 


W hen posting a follow-up to an article or replying direct to the author of an article viaemail, the text of the aticle can be 
quoted. T he beginning of the quoted text can contain information about the quoted article (for example, the N ameand the 
M essage 1D of the article). To allow for different situations, certain information from the article can be used in the quoted 
string. The following variables are expanded if found in the tinrc variables mail_quote_format= OF news_quote_format=: 
A Address (e-mail) 

Date 

Full address (%N (%A)) 

Groupname 

M essage | D 

N N ame of user 


we £ LP LC 
= Oo 1 0 


oe 


For example, 


mail_quote_format=0n %D in %G you wrote: 
news_quote_format=In %M, %F wrote: 


would expand when used to: 


On 21 Jul 1992 09:45:51 -0400 in alt.sources you wrote: 
In <abcINN123@an1433.uucp>, Iain Lea (iain@erlm.siemens.de) wrote: 


MAILING, PIPING, PRINTING, REPOSTING, AND SAVING ARTICLES 
Thecommand interface to mail (m), pipe (|), print (0), crosspost (x) and save (s) articles isthe same for ease of use. 


The initial command will ask you to select which article thread, hot (autosdected) regex pattern, tagged articles you wish to 
mail, pipe, and so on. 
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Tagged articles must have already been tagged with the T command. All tagged articles can be untagged by theu untag 
command. 


If regex pattern matching is sdected, you are asked to enter a regular expression (for example, to match all article subject 
lines containing net News, you must enter *net News*). Any articles that match the entered expression will be mailed, 
piped, and so on. 


To save articles to a mailbox with the nameof the current newsgroup (for example, Alt. sources) enter = or =<mailbox 
name> when asked for the save filename. 





To save articles in <newsgroup name>/<filename> format, enter +<filename>. 


When saving articles, you can specify whether the saved files should be post processed (such aSunshar shell archive, 
uudecode multiple parts, and so on). A default process type can be set by the Process type in them O ptions menu. 


AUTOMATIC MAILING AND SAVING NEW NEWS 


tin allows new/unread news articles to be mailed (-m option)/saved (-s option) in batch mode for later reading— useful 
whe going on holiday and you don’t want to return and find that expire has renoved a whole load of unread articles. It’s 
best to run from crontab every day while away, after which you will be mailed a report of which articles were mailed/saved 
from which newsgroups and the total number of articles mailed/saved. Articles are saved in a private news structure under 
your <savedir> directory (default is $HOME /News). 


Be careful of using this option if you read a lot of groups because you could overflow your filesystem. If you only want to 
save a few groups, it would be best to back up your full $HoME/.newsrc and create a new one that only contains the 
newsgroups you want to mail/save. Saved news can be read later by tin -r. 


tin -M iain -c -f newsrc.mail M ail any unread articles in newsgroups specified in file newsrc.mail 


tin -S -c -f newsrc.save Save any unread articles in newsgroups specified in filenewsrc.save 
tin -R Read any articles saved by tin -s 
SIGNATURES 


tin will recognizea signature in either $HOME/. signature OF $HOME/.Sig. If $HOME/. signature exists, then the signature 
will be pulled into the editor for mail commands. A signature in $HoME/.signature will not be pulled into the editor for 
posting commands because inews will append the signature itself. 


A signature in $Home/.Sig will be pulled into the editor for both posting and mailing commands. 
The following is an example of a $HOME/.Sig file 


NAMES Iain Lea iain. lea@erlm.siemens.de 
SNAIL Bruecken Strasse 12, 8500 Nuernberg 90, Germany 
PHONE +49-911-331963 (home) +49-911-3089-407 (work) 


tin also has the capability to generate random signatures on a per-newsgroup basis if so desired. T he way to accomplish this 
is to specify the default signature or the group attribute sigfile as a directory. If, for example, the sigfile path is /usr/iain/ 
.sigs and .sigs isadirectory, then tin will select a random signature from any file that is in the directory .sigs (note one 
signature per numbered file). A random signature can also consist of a fixed part signature that can contain your name, 
address, and so on, followed by the random sig. T hefixed part of the random sigisread from the file $HOME/.sigfixed. 


ENVIRONMENT VARIABLES 


TINRC D efine this variable if you want to specify command-line options that tin should bestarted with to 
save typing then each timeit is started. T he contents of the environment variable are added to the 
front of the command-line options before it is parsed, therefore allowing an option specified on the 
command line to override the same option specified in the environment. 

TIN_HOMEDIR Define this variableif you do not want the . tin directory in $HomE/.tin. For example, if you want 
all tin’s private files in /tmp/.tin, you would set TINDIR to /tmp. 


TIN_INDEXDIR 


TIN_LIBDIR 


TIN_SPOOLDIR 


TIN_NOVROOTDIR 


TIN_ACTIVEFILE 


NNTPSERVER 


DISTRIBUTION 


ORGANIZATION 


REPLYTO 


ADD_ADDRESS 


BUG_ADDRESS 


MAILER 


VISUAL 


AUTOSUBSCRIBE 
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D efine this variable if you do not want the . index directory in $HOME/.tin/.index. For example 
if you want all tin’sindex filesin /tmp/.index, you would set TIN_INDEXDIR to /tmp. 

D efine this variable if you want to override the Ltap1R path that was compiled into the tin binary 
via the Makefile. 
D efine this variable if you want to override the spooLoir path that was compiled into thetin 
binary via the Makefile. 

D efine this variable if you want to override the novrootopir path that was compiled into the tin 
binary via the Makefile. 

D efine this variable if you want to override the L1BD1R/active path that was compiled into the tin 
binary via the Makefile. 

The default N NTP server to renotedy read news from. This variable only needs to be set if the -r 
command-line option is specified and the file /etc/nntpserver does not exist. 

Set the article header fidd “Distribution:” to the contents of the variable instead of the system 
default. 

Se the article header fidd “O rganization:” to the contents of the variable instead of the system 
default. This variable has precedence over the file $HOME/ . tin/organization that may also contain 
an organization string. If you are reading news on an Apollo DomainOS machine, the environment 
variable newsorc has to be used instead of ORGANIZATION. 

Se the article header fidd “Reply-T o:” to the return address specified by the variable T his is useful 
if the machine is not registered in the UUCP mail mapsor if you wish to receive replies at a 
different machine. T his variable has precedence over the file SHOoME/. tin/replyto that may also 
contain areturn address. 

This can contain an address to append to thereturn address when replying directly through mail to 
somebody whose mail address is not directly recognized by the local host. For example say the 
return address is user@bigvax, but bigvax isnot recognized by your host, so therefore the mail 
will not reach user. But the host 1ittevax is known to recognize your host and bigvax, 50 if 
ADDADDRESS is set (for example, setenv ADD_ADDRESS @littevax for csh or 

set ADD_ADDRESS @littevax 

and export ADD_ADDRESS for sh), the address 

user@bigvax@littlevax will be used and the mail will reach user@bigvax. 

This variable has precedence over the file 

$HOME/.tin/add_address 

that may also contain an address. 

If the B command bug report mail address is not correct, this variable should be set to the correct 
mail address. T his variable has precedence over the file 

$HOME/.tin/bug_address 

that may also contain a mail address. 

This variable has precedence over the default mailer that is used in all mailing operations within 
tin (for example, replying rr, and bug reports B). 

This variable has precedence over the default editor (for example, vi) that is used in all editing 
operations within tin (for example, posting w, replying rr, follow-ups fF, and bug reports B). 

tin interprets this variable similarly to rn. It contains a list of patterns, separated by commas and 
possibly prefixed with exclamation points. A new group is checked against the list of patterns; if it 
matches, tin subscribes the user to the group without further query. An exclamation point negates 
the meaning of a match on this pattern and can be used to cancel certain matches. For example, 
setting AUTOSUBSCRIBE=comp.os.unix.*,talk.*, !talk.politics.* will automatically subscribe 
the user to all newsgroupsin the comp.os.unix hierarchy, and all talk groups other than 
talk.politics groups (which will be queried for as usual). 
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AUTOUNSUBSCRIBE tin interprets this variable similarly to rn. It is handled like the AuTosUBSCRIBE variable, but 
groups matching the list are unsubscribed from without further query. For example, setting 
AUTOUNSUBSCRIBE=alt .flame.*,u*, !uk.* will automatically unsubscribe the user from all new 
alt.flame groups and all groups starting with u (university groups) other than uk groups (which 
will be queried for as usual). 


TIPS AND TRICKS 


tin can pretty much be navigated by using the four cursor keys. The left-arrow key goes up alevd, the right-arrow key goes 
down alevel, the up-arrow key goes up aline (or page, at article viewer level) and the down-arrow key goes down a line (or 
page, at article viewer level). 


The following newsgroups provide useful information concerning news software: 





- -news. software. readers Information about news user agents tin, rn, nn, vn, and so on 
--news.software.nntp Information about N NTP 

- -news.software.b Information about news transport agents Bnews, Cnews, and INN) 
- -news.answers Frequently asked questions (FAQs) about many different themes 


M any prompts (for example, Mark everything as read? (y/n):) within tin offer a default choice that the cursor is 
positioned on. When you press <C R>, the default value is taken. 


M any prompts (for example, Post subject []>) within tin can beaborted by pressing <ESC >. 
When tinisrun in an xterm window, it will resize itsdf each time the xterm is resized. 
tin will reread the active file at set intervals to show any newly arrived news. 


xterm BUTTONS 
If the environment variable TERM is set to xterm, then button pressing can beused to select groups and articles. 
In theGroup Sdection menu, if the mouseis pointing before the group’s listing region, the previous page is selected (just 
like b). If the mouse is pointing after the group’s listing region, the next page is sdected (just like space). If the mouse is 
pointing at agroup, then 
Left button M oves to the group pointed at 
Other buttons Moveto and select the group pointed at, just like <cr> 


In the Article menu, if the mouse is pointing before the article listing region, the previous page is sdected (just like b). If the 
mouse is pointing after the article listing region, the next page is sdected (just like space). If the mouse is pointing at an 
article, then 

Let button M oves to the article pointed at 

Cente button Readsnext unread articlefrom that pointed at, just like <TaB> 

Right button Reads article pointed at, just like <cr> 


In the Thread menu, if the mouse is pointing before the article listing region, the previous page is selected (just likeb). If the 
mouse is pointing after the article listing region, the next page is sdected (just like space). If the mouse is pointing at an 
article, then 


Left button M oves to the article pointed at 

Cente button Reads next unread articlefrom that pointed at, just like <T AB> 

Right button Reads article pointed at, just like <CR> 

In the Spool Selection menu, if the mouse is pointing before the spool listing region, the previous page is selected (just like 


b). If the mouse is pointing after the spool listing region, the next page is selected (just like space). If the mouse is pointing 
at a spool selection, then 
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In other menus and areas, button pressing reverts back to usual cut and paste of xterm, but after one click of any button. 


Let button M oves to the spool pointed at 
Other buttons Moveto and select the spool pointed at, just like <cr> 














FILES 
$HOME/ . newsrc Subscribed to newsgroups 
$HOME /. newsauth nntpserver password pairs for NN TP servers that require authorization 
$HOME/.tin/tinrc Options 
$HOME/.tin/attributes Contains user-specified group attributes 
$HOME /.tin/ .index N ewsgroups index files directory 
$HOME/.tin/ .mailidx M ailgroups index files directory 
$HOME/.tin/.saveidx Saved newsgroups index files directory 
$HOME/.tin/active.mail Active file of users mailgroups 
$HOME/.tin/active.save Active file of users saved newsgroups 
$HOME/.tin/add_address Address to add to when replying through mail 
$HOME/.tin/bug address Address to send bug reports to 
$HOME/.tin/kill Article kill and autoselection file 
$HOME/.tin/organization String to replace default organization 
$HOME/.tin/posted H istory of articles posted by user 
$HOME/.tin/replyto H ost address to usein “Reply-T 0:” mail header 
$HOME/. signature Signature 
$HOME/.Sig Signature 
$HOME/.sigfixed Fixed part of arandomly generated signature 
/usr/1lib/news/motd N ews message-of-the-day file 
/usr/1ib/news/newsgroups Short description of all navsgroups 
/usr/1lib/news/subscriptions List of newsgroups to subscribe first-time user to 
BUGS 


There are bugs somewhere among the creeping featurism. Any bugs found should be reported by thes (bug report) 
command. 


Coredumps when setting certain toggle options from the O ptions menu at article viewer level. 
Coredumps when killing last article in a thread at article viewer level. 


HISTORY 


Based on the tass newsreader that was developed by Rich Skrenta and posted to alt. sources in M arch 1991. tass was 
itself heavily influenced by notes, which was devdoped at the University of Illinois by Ray Essick and Rob Kolstad in 1982. 


v1.0 PL@ (full) was posted in eight parts to alt. sources on 23 Aug 1991. v1.@ PL1 (full) was posted in eight parts to 
alt.sources on 03 Sep 1991. v1.0 PL2 (full) was posted in nine partsto alt.sources on 24 Sep 1991. v1. PL3 (patch) 
was posted in four partsto alt. sources on 30 Sep 1991. v1.@ PL4 (patch) was posted in two parts to alt. sources on 02 
Oct 1991. v1.0 PLs5 (patch) was posted in four parts to alt. sources On 17 Oct 1991. v1.0 PLé (patch) was posted in five 
parts to alt. sources on 27 Nov 1991. v1.@ PL7 (patch) was posted in two parts to alt. sources on 27 N ov 1991. v1.1 
PL@ (full) was posted in eleven parts to alt.sources on 13 Feb 1992. v1.1 PL (full) was posted in twelve parts to 
alt.sources on 24 M ar 1992. v1.1 pL2 (patch) was posted in four parts to alt. sources on 30 Mar 1992. v1.1 pLs (full) 
was posted in fifteen parts to alt.sources on 13 M ay 1992. v1.1 pPL4 (full) was posted in fifteen parts to alt. sources on 
22 Jun 1992. v1.1 PLS5 (patch) was posted in seven parts to alt. sources on 11 Aug 1992. v1.1 Pte (full) was posted in 
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fifteen parts to alt.sources on 14 Sep 1992. v1.1 PL7 (patch) was posted in ten parts to alt. sources on 15 Nov 1992. 
v1.1 PL8 (patch) was posted in six parts to alt. sources on 06 D ec 1992. v1.1 PLg (patch) was posted in three parts to 
alt.sources on 20 Mar 1993. v1.2 PLo (full) was posted in fourteen parts to alt. sources on 25 M ay 1993. v1.2 PL1 
(patch) was posted in eight parts to alt. sources on 14 Jul 1993. v1.2 PL2 (patch) was posted in parts to alt. sources in 


September 1993. 
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tload 


tload— Graphic representation of system load average 


SYNOPSIS 
tload [-s scale] [-d delay] [tty] 

DESCRIPTION 
tload prints a graph of the current systen load average to the specified tty (or the tty of the t1oad process if noneis 
specified). 

OPTIONS 


The -s scale option allows a vertical scale to be specified for the display (in characters between graph ticks); thus, a smaller 
value reoresents a larger scale, and vice versa. 


The -d delay setsthe delay between graph updates in seconds. 


FILES 

/proc/loadavg Load average information 
SEE ALSO 

ps(1), top(1), uptime(1), w(1) 
BUGS 


The -d delay option sets the time argument for an alarm(2); if -a @ isspecified, the alarm is set to @, which will never send 
the SIGALRM and update the display. 


AUTHORS 
Branko Lankester, D avid Engd (david@ods.com), and M ichad K. Johnson (johnsonm@sunsite.unc. edu) 
Cohesive Systems, 20 M arch 1993 


top 
top— Display top CPU processes 
SYNOPSIS 


top [-][ddel ay ][q][S][s]{i] 


DESCRIPTION 


top provides an ongoing look at processor activity in real time. It displays a listing of the most CPU -intensive tasks on the 
system, and can provide an interactive interface for manipulating processes. 
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COMMAND-LINE OPTIONS 


d 
q 


i 


FIELD DESCRI 


Specifies the delay between screen updates. You can change this with the s interactive command. 

T his causes top to refresh without any delay. If the caller has superuser privileges, top runs with the highest 
possible priority. 

Specifies cumulative mode, where each process is listed with the CPU time that it as well as its dead children has 
spent. This is like the -s flag to ps(1). See the discussion of thes interactive command later in this manual page. 


T alls top to run in secure mode. T his disables the potentially dangers of the interactive commands. (See 
“Interactive Commands,” later in this manual page.) A secure top is anifty thing to leaverunning on aspare 
terminal. 


Start top, ignoring any idle or zombie processes. (See the interactive command i.) 


PTIONS 


top displays a variety of information about the processor state The display is updated every five seconds by default, but you 
can change that with the d command-line option or the s interactive command. 


uptime This line displays the time the system has been up, and the three load averages for the system. The load 
averages are the average number of process ready to run during the last 1, 5, and 15 minutes. T his lineis 
just like the output of uptime(1). 

processes The total number of processes running at the time of the last update. This is also broken down into the 
number of tasks that are running, sleeping, stopped, or undead. 

CPU states Shows the percentage of CPU timein user mode systen mode, niced tasks, and idle (N iced tasks are only 
those whose nice value is negative.) Time spent in niced tasks will also be counted in system and user 
time, so the total will be more than 100 percent. 

Mem Statistics on memory usage, including total available memory, free memory, used memory, shared 
memory, and memory used for buffers. 

Swap Statistics on swap space, including total swap space available swap space, and used swap space This and 
Mem are just like the output of free(1). 

PID Theprocess|D of each task. 

USER The username of the task’s owner. 

PRI The priority of the task. 

NI The nice value of the task. N egative nice values are lower priority. 

SIZE The size of the task’s code plus data plus stack space, in kilobytes, is shown here. 

RSS The total amount of physical memory used by the task, in kilobytes, is shown here. 

SHRD The amount of shared memory used by the task is shown in this column. 

ST T he state of the task is shown here. The state is ather s for seeping, p for uninterruptible sleep, r for 
running, z for zombies, or T for stopped or traced. 

TIME Total CPU time the task has used since it started. If cumulative mode ison, this also includes the C PU 
time used by the process's children that have died. You can set cumulative mode with thes command-line 
option or toggle it with the interactive command s. 

%CPU The task’s share of the CPU time since the last screen update, expressed as a percentage of total CPU time. 

SeMEM The task’s share of the physical manory. 

COMMAND The task’s command name, which will be truncated if it is too long to be displayed on one line. T asks in 
memory will havea full command line but swapped-out tasks will only have the name of the program in 
parentheses, for example, (getty). 

INTERACTIVE COMMANDS 
Several single key commands are recognized while top is running. Some are disabled if the s option has been given on the 


command 


line 
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“L Erases and redraws the screen. 
hor ? Displays a hap screen giving a brief summary of commands, and the status of secure and cumulative modes. 
k Kill a process. You will be prompted for the pr1p of the task, and the signal to send to it. For anormal kill, send 


signal 15. For asure, but rather abrupt, kill, send signal 9. The default signal, as with ki11(1), iS15, SIGTERM. 
This command is not available in secure mode. 

i Ignore idle and zombie processes. T his is a toggle switch. 

nor# Change the number of processes to show. You will be prompted to enter the number. T his overrides automatic 
determination of the number of processes to show, which is based on window size measurenent. If @ is specified, 
then top will show as many processes as will fit on the screen; this is the default. 

q Quit. 

r Renice a process. You will be prompted for the p1p of the task, and the value to niceit to. Entering a positive 
value will cause a process to be niced to negative values, and lose priority. If root is running top, a negative value 
can be entered, causing a process to get ahigher than normal priority. The default renice value is 10. This 
command is not available in secure mode. 

s This toggles cumulative mode, the equivalent of ps -s, in other words, that CPU times will include a process's 
defunct children. For some programs, such as compilers, which work by forking into many separate tasks, normal 
mode will make then appear less denanding than they actually are For others, however, such as shells and init, 
this behavior is correct. In any case try cumulative mode for an alternative view of CPU use. 

s Change the dday between updates. You will be prompted to enter the delay time in seconds, between updates. 
Fractional values are recognized down to microseconds. Entering @ causes continuous updates. T he default value 
is5 seconds. N ote that low values cause nearly unreadably fast displays, and greatly raise the load. T his command 
isnot available in secure mode. 


NOTES 


This proc-based top works by reading the files in the proc filesystem, mounted on /proce. If /proc isnot mounted, top will 
not work. 


scPu shows the cputime/realtime percentage in the period of time between updates. For the first update, a short delay is 
used, and top itself dominates the C PU usage. After that, top will drop back, and amore rdiable estimate of CPU usage is 
available. 


Thesz1ze and rss fields don’t count the page tables and the task struct of a process; this isat least 12K of memory that is 
always resident. s1ze is the virtual size of the process (code+data+stack). 


Keep in mind that a process must die for its time to be recorded on its parent by cumulative mode. Perhaps more useful 
behavior would be to follow each process upwards, adding time, but that would be more expensive, possibly prohibitively so. 
In any case, that would make top’s behavior incompatible with ps. 


SEE ALSO 


ps(1), free(1), uptime(1), kil1(1), renice(1). 


BUGS 


If the window isless than about 70x7, top will not format information correctly. 


AUTHOR 
top was originally written by Roger Binns, based on Branko Lankester’s (lankeste@fwi.uva.n1) ps program. Robet N ation 
(nation@rocket. sanders. lockheed.com) rewrote it significantly to use the proc filesystem, based on M ichad K. Johnson's 
(johnsonm@sunsite.unc.edu) proc-based ps program. M any changes were made, including secure and cumulative modes 
and a general cleanup, by M ichael Shields (mj shield@nyx.cs.du.edu). 


Linux, 1 February 1993 
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touch 


touch— Change file timestamps 


SYNOPSIS 
touch [-acfm] [-r reference-file] [-t MMDDhhmm[[CC]YY][.ss]] [-d time] 
[--time={atime, access, use, mtime, modify}] [--date=time] [--file=reference-file] 
[--no-create] [--help] [--version] file... 


DESCRIPTION 


This manual page documents the GN U version of touch. touch changes the access and modification times of each given file 
to the current time. Files that do not exist are created empty. If the first filename given would bea valid argument to the -t 
option and no timestamp is given with any of the -d, -r, or -t options and the - - argument is not given, that argument is 
interpreted as the time for the other files instead of as a filename. 


If changing both the access and modification times to the current time, touch can change the timestamps for files that the 
user running it does not own but has write permission for. O therwise, the user must own the files. 


OPTIONS 
-a, --time=ati me, Change the access time only. 
--time=access, 
--time=use 
-C, --no-create Do not create files that do not exist. 
-d, --date time Useti me (which can bein various common formats) instead of the current time It can 
contain month names, time zones, am and pm, and so on. 
-f Ignored; for compatibility with BSD versions of touch. 
-m, --time=mti me, Change the modification time only. 


--time=modi f y 
-r, --file reference-file Usethe times of ref erence-file instead of the current time. 


-t MMDDhhmm{[CC]¥Y]J[.ss] | Usethe argument (months, days, hours, minutes, optional century and years, optional 
seconds) instead of the current time. 


--help Print a usage message on standard output and exit successfully. 
- -version Print version information on standard output, then exit successfully. 


GNU FileUtilities 


tr 


tr— Translate or ddete characters 


SYNOPSIS 


tr [-cst] [--complement] [--squeeze-repeats] [--truncate-set1] stringl string2 
tr f-s,--squeeze-repeatsg [-c] [--complement] stringl 

tr f-d,--deleteg [-c] stringl 

tr f-d,--deleteg f-s,--squeeze-repeatsg [-c] [--complement] stringl string2 


GNU tr also accepts the - -help and - - version options. 


tr 537 


DESCRIPTION 


This manual page documents the GN U version of tr. tr copies the standard input to the standard output, performing one 
of the following operations: 


m@ Translate and optionally squeeze repeated characters in the result 
m Squeeze repeated characters 

m Ddee characters 

m Ddete characters, then squeeze repeated characters from the result. 


Thestring1 and (if given) st ring2 arguments define ordered sets of characters, referred to bdow aSset1 andset2. These 
sets are the characters of the input that tr operates on. The - -complement (-c) option replaces s et 1 with itscomplement (all 
of the characters that are not inset1). 


SPECIFYING SETS OF CHARACTERS 


The format of thest ring1 andstring2 arguments resembles the format of regular expressions; howeve,, they are not regular 
expressions, only lists of characters. M ost characters simply represent themselves in these strings, but the strings can contain 
the shorthands in the following list, for convenience. Some of than can be used only instring1 Orstring2, as noted. 


Backslash escapes. A backslash followed by a character not listed causes an error message. 


\a Control-G 
\b Control-H 
\f Control-L 
\n Control-J 
xc Control-M 
\t Control-I 
\v Control-K 
\o0o0 The character with the value given by 000, which is 1 to 3 octal digits 
\n A backslash 


Ranges. T he notation m-n expands to all of the characters from m through n, in ascending order. m should collate before n; if 
it doesn’t, an error results. As an example, 0-9 isthe same as 0123456789. Although GN U tr does not support the System 
V syntax that uses square brackets to enclose ranges, translations specified in that format will still work as long as the brackets 
iNstringl correspond to identical brackets inst ring2. 


Repeated characters. The notation [c*n] instring2 expands to n copies of character c. Thus, ty*6] isthe same a yyyyyy. 
Thenotation [c*] in st ring2 expands to as many copies of c as areneeded to makes et 2 aSlong aSset1.If nbeginswith a 
a, it isinterpreted in octal, otherwise in decimal. 


Character classes. The notation [:class-name:] expands to all of the characters in the (predefined) class named class - 
name. T he characters expand in no particular order, except for theupper and lower classes, which expand in ascending 
order. When the - -delete (-d) and - -squeeze-repeats (-s) options are both given, any character class can be used in 

st ring2. Otherwise only the character classes lower and upper are accepted in string2, and then only if the corresponding 
character class (upper and lower, respectively) is specified in the same relative position inst ring1. Doing this specifies case 
conversion. T he class names are given in the following list; an error results when an invalid class name is given. 

alnum Letters and digits 

alpha Letters 

blank H orizontal whitespace 

entrl Control characters 

digit Digits 

graph Printable characters, not including space 

lower Lowercase letters 
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print Printable characters, including space 
punct Punctuation characters 

space H orizontal or vertical whitespace 
upper U ppercase letters 

xdigit Hexadecimal digits 


Equivalence classes. T he syntax [=c =] expands to all of the characters that are equivalent to c, in no particular order. 
Equivalence classes are a recent invention intended to support non-English alphabets. But there seems to beno standard way 
to define then or determine their contents. Therefore, they are not fully implemented in GN U tr; each character's 
equivalence class consists only of that character, which makes this a usdess construction currently. 


TRANSLATING 


tr performs translation when st ring1 and string2 areboth given and the - -delete (-d) option is not given. tr translates 
each character of its input that isinset1 to thecorresponding character in s et 2. Characters not in set 1 are passed through 
unchanged. W hen a character appears more than onceinset1 and the corresponding characters inset 2 arenot all the same 
only the final oneis used. For example, these two commands are equivalent: 


tr aaa xyz 


traz 


A common use of tr isto convert lowercase characters to uppercase. This can be donein many ways. H ere are three of them: 
tr abcdefghij klmnopqrstuvwxyz ABCDEFGHIUKLMNOPQRS TUVWXYZ 


tr a-z A-Z 


tr '[:lower:]' '[:upper:]' 
When tr is performing translation, set 1 andset2 should normally havethe same length. If set1 isshorter than set2, the 
extra characters at the end of set 2 are ignored. 


On the other hand, makings et1 longer than s et 2 isnot portable; PO SIX.2 says that the result is undefined. In this 
situation, the BSD tr padsset2 to thelength of set 1 by repeating the last character of s et 2 as many times as necessary. T he 
System V tr truncatesset1 to thelength of set2. 


By default, GN U tr handles this caseliketheBSD tr does. When the - -truncate-set1 (-t) option isgiven, GNU tr 
handles this case like the System V tr instead. This option isignored for operations other than translation. 


Acting like the System V tr in this case breaks the relatively common BSD idiom: 

tr -cs A-Za-z0-9 'n012' 

because it converts only zero bytes (the first dement in the complement of s et 1), rather than all nonalphanumaiics, to 
newlines. 


SQUEEZING REPEATS AND DELETING 


When given just the - -delete (-d) option, tr removes any input characters that areinset1. 


When given just the - -squeeze-repeats (-s) option, tr replaces each input sequence of a repeated character thatisinset1 
with a single occurrence of that character. 


W hen given both the - -delete and the - -squeeze- repeats options, tr first performs any deletions using set1, then 
squeezes repeats from any remaining characters usings et 2. 


The - -squeeze-repeats option may also be used when translating, in which case tr first performs translation, then squeezes 
repeats from any remaining characters using set 2. 


H ere are some examples to illustrate various combinations of options. 


ts, rest 


Put all words on lines by themsdves. T his converts all nonalphanumeric characters to newlines, then squeezes each string of 
repeated newlines into a single newline: 


tr -cs '[a-zA-Z0-9]' '[nn*]' 


Remove all zero bytes: 
tr -d 'n000' 


Convert each sequence of repeated newlines to a single newline 
tr -s ‘nn' 
GNU tr also accepts the following optionsin any combination with the others. 


--help Print a usage message and exit with a non-zero status. 
--version Print version information on standard output, then exit. 


WARNING MESSAGES 


Setting the environment variable PosrxLy_correct turns off several warning and error messages, for strict compliance with 
POSIX.2. The messages normally occur in the following circumstances: 


1. When the- -delete option is given but --squeeze-repeats iSnot, andstring2 isgiven, GNU tr by default prints a 
usage message and exits, because st ri ng2 would not be used. T he posix specification says that st ring2 must beignored 
in this case. Silently ignoring arguments is a bad idea. 

2. When an ambiguous octal escape is given. For example n4ao is actually n4@ followed by the digit 0, because the value 
400 octal does not fit into a single byte. 


N ote that GN U tr does not provide complete BSD or Systen V compatibility. For example there isno option to disable 
interpretation of the PO SIX constructs [:alpha:], [=c=], and [c*10]. Also, GNU tr doesnot delete zero bytes automati- 
cally, unlike traditional UNIX versions, which provide no way to preserve zero bytes. 


GNU Tet Utilitie 


tset, reset 


tset, reset— T erminal initialization 


SYNOPSIS 


tset [-IQrs] [-t] [-e ch] [-i ch] [-k ch] [-m mapping] [terminal] 
tset -h 

tset -V 

reset [-IQrs] [-t] [-e ch] [-i ch] [-k ch] [-m mapping] [terminal] 
reset -h 

reset -V 


DESCRIPTION 


tset initializes terminals. tset first determines the type of terminal that you are using. T his determination is done as 
follows, using the first terminal type found: 


m Theteminal argument specified on the command line 

m Thevalue of the TERM vironmental variable 

m Theterminal type associated with the standard error output devicein the /etc/ttytype file 
m Thedeault teminal type, unknown 
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If the terminal type was not specified on the command line, the -m option mappings are then applied (see the following 
section, “O ptions,” for more information). Then, if the terminal type begins with a question mark (2), theuser is prompted 
for confirmation of the teminal type. An empty response confirms the type or, another type can be entered to specify anew 
type. After the terminal type has been determined, the termcap entry for the terminal is retrieved. If no termcap entry is 
found for the type, the user is prompted for another terminal type. 


After the termcap entry is retrieved, the window size, backspace interrupt, and line kill characters (among many other 
things) are set and the terminal and tab initialization strings are sent to the standard error output. Finally, if the erase 
interrupt, and line kill characters have changed, or are not set to their default values, their values are displayed to the standard 
error output. 


W hen invoked as reset, tset sets cooked and echo mode, turns off cbreak and raw modes, turns on newline translation and 
resets any unset special characters to their default values before doing the terminal initialization described above Thisis 
useful after a program dies leaving aterminal in an abnormal state. N ote, you may have to type <LF>reset<LF> (the line-feed 
character is normally contro1-u) to get the terminal to work, as carriage-return may no longer work in the abnormal state. 
Also, the terminal will often not echo the command. 


OPTIONS 


The options are as follows: 


-t The terminal type is displayed to the standard output, and the terminal is not initialized in any way. 

-e Set the erase character to ch. 

“I Do not send theteminal or tab initialization strings to the taminal. 

“i Sé@ the interrupt character to ch. 

-k Se the line kill character to ch. 

-m Specify a mapping from a port type to aterminal. See the following section, “Setting the Environment,” for more 
information. 

-r Print the taminal type to the standard error output. 

“8 Print the sequence of shell commands to initialize the environment variables coLUMNS, LINES, TERM, and TERMCAP 
to the standard output. 

Q Don’t display any values for the erase, interrupt, and line kill characters. 

“Ww Force setting of display size as defined in /etc/termcap file. 

-h Print short usage message. 

-V Print version number. 


The arguments for the -e, -i, and -k options may eather be entered as actual characters or by using the hat notation, for 
example, control-h may be specified as* Hor” h. 


SETTING THE ENVIRONMENT 


It is often desirable to set the terminal type and information about the terminal's capabilities and display size in the shal’s 
environment. T his is done with the -s option; when this option is specified, the commands to enter the information into the 
shell’s environment are output to the standard output. If the sHELL environmental variable ends in csh, the output 
commandsare for the csh(1); otherwise, they are for sh(1). N ote, the output commands for the csh set and unset the shell 
variable nogiob. T he following linein the .1ogin or . profile files will initializethe environment correctly: 


eval 'tset -s options ... ' 


TERMINAL TYPE MAPPING 


When the terminal is not hardwired into the system (or the current systen information is incorrect), the terminal type 
derived from the /etc/ttytype file or the TERM environmental variable is often something gmeric like network, dialup, or 
unknown. When tset is used in astartup script . profile for sh(1) users or . login for csh(1) users), it is often desirable to 


tse, rest 


provide information about the type of terminal used on such ports. T he purpose of the -m option isto map from some set of 
conditions to aterminal type that is, to tdl tset, “If|’m on this port at a particular speed, guess that I’m on that kind of 
terminal.” 


The argument to the -m option consists of an optional port type an optional operator, an optional baud rate specification, an 
optional colon (:) character, and aterminal type. The port type is a string (ddimited by either the operator or the colon 
character). T he operator may be any combination of: a>, &<, &@, and &!; &> means greater than, a< meansless than, ae 
means equal to, and &! inverts the sense of the test. T he baud rate is specified asa number and is compared with the speed of 
the standard error output (which should be thecontrol terminal). The terminal type isa string. 


If the terminal type is not specified on the command line, the -m mappings are applied to theterminal type. If the port type 
and baud rate match the mapping, the terminal type specified in the mapping replaces the current type If more than one 
mapping is specified, the first applicable mapping is used. 


For example, consider the following: 
dialup>9600:vt100 


The port type is dialup, the operator is >, the baud rate specification is 9600, and the terminal type is vt10e . The result of 
this mapping is to specify that if the terminal type is dialup, and the baud rate is greater than 9600 baud, a terminal type of 
vt10@ will be used. 


If no port typeis specified, the terminal type will match any port type; for example, 
-m dialup:vt100 -m :?xterm 

will cause any dialup port, regardless of baud rate, to match theterminal type: 
vt100, 

and any nondialup port type to match the terminal type: 

?xterm. 


N ote, because of the leading question mark, the user will be queried on a default port as to whether they are actually using an 
xterm terminal. 


N o whitespace characters are permitted in the -m option argument. Also, to avoid problems with metacharacters, it is 
suggested that the entire -m option argument be placed within single quote characters, and that csh users insert a backslash 
character (\) before any exclamation marks (1). 


ENVIRONMENT 
Thetset command utilizes the SHELL and TERM environment variables. 


tset Can Se COLUMNS, LINES, TERM, and TERMCAP environmental variables. 


FILES 
/etc/ttytype system Port nameto terminal type mapping database 
/etc/termcap Terminal capability database 
SEE ALSO 
esh(1), tcsh(1), sh(1),bash(1),stty(1), tty(4), termcap(5), ttytype(5), environ(7) 
HISTORY 


The tset command appeared in BSD 3.0. 
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COMPATIBILITY 


The -A, -E, -h, -S, -u, and -v options have been ddeted from the tset utility. None of than were documented in 4.3BSD 
and all are of limited utility at best. The -a, -d, and -p options are similarly not documented or useful, but were retained as 
they appear to bein widespread use. It is strongly recommended that any usage of these three options be changed to use the 
-m option instead. The -n option remains, but has no effect. It is still permissible to specify the -e, -i, and -k options 
without arguments, although it is strongly recommended that such usage be fixed to explicitly specify the character. 


Executing tset aS reset no longer implies the -a option. Also, the interaction between the - option and the terminal 
argument in some historic implementations of tset has been removed and has been replaced with -+ option. 


Finally, the tset implementation has been completely redone as part of the addition to the systen of alEEE Std1003.1- 
1988 (PO SIX) -compliant terminal interface and will no longer compile on systems with older terminal interfaces. 


Linux, 12 January 1995 


tsort 


tsort— T opological sort of a directed graph 


SYNOPSIS 


tsort [file] 


DESCRIPTION 


tsort takes a list of pairs of node names representing directed arcs in agraph and prints the nodes in topological order on 
standard output. Input is taken from the named file, or from standard input if no file is given. 


N ode namesin the input are separated by whitespace, and there must be an even number of nodes. 


Presence of anode in agraph can be represented by an arc from the node to itself. This is useful when anode isnot 
connected to any other nodes. 


If the graph contains a cycle (and therefore cannot be properly sorted), one of the arcs in the cycleis ignored and the sort 
continues. Cycles are reported on standard error. 


SEE ALSO 
ar(1) 


HISTORY 


A tsort command appeared in AT&T v7. Thistsort command and manual page are derived from sources contributed to 
Berkeley by M ichael Rendall of M emorial University of N ewfoundland. 


23 April 1991 
twm 
twm— T ab Window M anager for the X Window System 
SYNTAX 
twm [ -display dpy ][-s ][-f initfile ][-v ] 
DESCRIPTION 


twm is a window manager for the X Window System. It provides titlebars, shaped windows, several forms of icon manage 
ment, user-defined macro functions, click-to-type and pointer-driven keyboard focus, and user-specified key and pointer 
button bindings. 


This program is usually started by the user’s session manager or startup script. When used from xdm(1) or xinit(1) without a 
session manager, twm is frequently executed in the foreground as the last client. When run this way, exiting twm causes the 
session to be terminated (logged out). 


By default, application windows are surrounded by a “frame” with a titlebar at the top and aspecial border around the 
window. The titlebar contains the window's name, arectangle that is lit when the window is receiving keyboard input, and 
function boxes known as titlebuttons at the left and right edges of the titlebar. 


Pressing pointer Button1 (usually the leftmost button unless it has been changed with xmodmap) on atitlebutton will invoke 
the function associated with the button. In the default interface windows are iconified by clicking (pressing and then 
immediately rdeasing) the left titlebutton (which looks like adot). Conversely, windows are deiconified by clicking in the 
associated icon or entry in the icon manager. (See description of the variable show- IconManager and of the function 

f . showiconmgr.) 


W indows are resized by pressing the right titlebutton (which resembles a group of nested squares), dragging the pointer over 
the edge that is to be moved, and releasing the pointer when the outline of the window is the desired size Similarly, windows 
are moved by pressing in the title or highlight region, dragging a window outline to the new location, and then rdeasing 
when the outline is in the desired position. Just clicking in the title or highlight region raises the window without moving it. 


W hen new windows are created, twm will honor any size and location information requested by the user (usually through - 
geometry command-line argument or resources for the individual applications). O therwise, an outline of the window’s 
default size itstitlebar, and lines dividing the window into a 3x3 grid that track the pointer are displayed. Clicking pointer 
Button] will position the window at the current position and give it the default size. Pressing pointer Button2 (usually the 
middle pointer button) and dragging the outline will give the window its current position but allow the sides to be resized as 
described above Clicking pointer Button3 (usually the right pointer button) will give the window its current position but 
attempt to make it long enough to touch the bottom of the screen. 


OPTIONS 
twm accepts the following command-line options: 


-display dpy | This option specifies the x server to use. 

-s This option indicates that only the default screen (as specified by -display or by the DISPLAY environ- 
ment variable) should be managed. By default, twm will attempt to manage all screens on the display. 

-f filename This option specifies the name of the startup file to use. By default, twm will look in the user’s home 
directory for files named .twmrc. num (where num is a screen number) or .twmrc. 

“Vv This option indicates that twm should print error messages whenever an unexpected X Error event is 
received. This can be useful when debugging applications but can be distracting in regular use 


CUSTOMIZATION 


M uch of twm’s appearance and behavior can be controlled by providing a startup file in one of the following locations 
(searched in order for each screen being managed when twm begins): 


$HOME/.twmrc.screennumber Thescreennumber iSagnall positive number (for example, a, 1, and so on) 
representing the screen number (for example, the last number in the DISPLAY 
environment variable host : displaynum. screennum) that would be used to contact 
that screen of the display. Thisis intended for displays with multiple screens of 
differing visual types. 

$HOME /. twmrc This is the usual name for an individual user’s startup file. 


<XRoot>/1ib/X11/twm/system.twmrc If neither of the preceding files are found, twm will look in this file for a default 
configuration. T his is often tailored by the site administrator to provide convenient 
menus or familiar bindings for novice users. <xRoot> refers to the root of theX11 
install tree. 
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If no startup files are found, twm will use the built-in defaults described. T he only resource used by twmis bitmapFilePath 
for a colon-separated list of directories to search when looking for bitmap files. For more information, see the Athena 
Widgets manual and xrab(1). 


twm startup files are logically broken up into three types of specifications: variables, Bindings, and Menus. The Variables 
section must come first and is used to describe the fonts, colors, cursors, border widths, icon and window placement, 
highlighting, autoraising, layout of titles, warping, and use of the icon manager. The Bindings section usually comes second 
and is used to specify the functions that should be invoked when keyboard and pointer buttons are pressed in windows, 
icons, titles, and frames. Themenus section gives any user-defined menus (containing functions to be invoked or commands 
to be executed). 


Variable names and keywords are case insensitive Strings must be surrounded by double quote characters (for example, 
“blue’) and are case-sensitive. A pound sign (#) outside of a string causes the remainder of the line in which the character 
appears to be treated asa comment. 


VARIABLES 


M any of the aspects of twm’s user interface are controlled by variables that may be set in the user's startup file Some of the 
options are abled or disabled simply by the presence of a particular keyword. O ther options require keywords, numbers, 
strings, or lists of all of these. 


Lists are surrounded by braces and are usually separated by whitespace or anewline For example, 


AutoRaise { "emacs" "XTerm" "Xmh" } 


or 


AutoRaise 

{ 
"emacs" 
"XTerm" 
"Xmh" 

} 


When a variable containing a list of strings reoresenting windows is searched (for example, to determine whether or not to 
enable autoraise, as shown in the preceding example), a string must bean exact, case-sensitive match to the window’s name 
(given by the ww_NAME window property), resource name, or class name (both given by thewm_cLass window property). The 
preceding example would enable autoraise on windows named emacs as well as any xterm (because they are of class xTerm) or 
xmh windows (which are of class xmh). 


String arguments that are interpreted as filenames (see Pixmaps, Cursors, and IconDirectory in the following list of 
variables) will prepend the user’s directory (specified by the Home environment variable) if the first character isa tilde (~). If, 
instead, the first character is a colon (:), the name is assumed to refer to one of the internal bitmaps that are used to create 
the default titlebars symbols: : x1ogo or :delete (both refer to thex logo), : dot or: iconify (both refer to the dot), : resize 
(the nested squares used by the resize button), : menu (a page with lines), and : question (the question mark used for 
nonexistent bitmap files). 


The following variables may be specified at the top of a twm startup file. Lists of Window name prefix strings are indicated by 
win-list. Optional arguments are shown in square brackets: 


AutoRaise { win-list ] This variable specifies a list of windows that should automatically be raised whenever the 
pointer enters the window. This action can be interactively enabled or disabled on 
individual windows using the function f. autoraise. 

AutoRelativeResize This variable indicates that dragging out a window size (either when initially sizing the 
window with pointer Button2 or when resizing it) should not wait until the pointer has 
crossed the window edges. Instead, moving the pointer automatically causes the nearest edge 
or edges to move by the same amount. T his allows the resizing of windows that extend off 
the edge of the screen. If the pointer is in the center of the window, or if the resize is begun 





by pressing atitlebutton, twm will still wait for the pointer to cross a window edge (to 
prevent accidents). This option is particularly useful for people who like the press- 
drag-release method of sweeping out window sizes. 
BorderColor string This variable specifies the default color of the border to be placed around all noniconified 
windows, [{ wincolorlist }] and may only begiven within acolor, Grayscale, Of Monochrome list. The optional 
wincolorlist specifies alist of window and color name pairs for specifying particular 
border colors for different types of windows. For example: 
BorderColor 
"gray50" 
{ 
"XTerm" "red" 
"xmh" "green" 


} 

The default is black. 
BorderTileBackground This variable specifies the default background color in the gray pattern used instring [4 
wincolorlist }] unhighlighted borders (only if NoHighlight hasn’t been set), and may only be given within 


aColor, Grayscale, OF Monochrome list. The optional wincolorlist allows pe-window 
colors to be specified. The default iswhite. 


BorderTileForeground This variable specifies the default foreground color in the gray pattern used in unhighlighted 

string [{ wincolorlist }] borders (only if NoHighlight hasn’t been set), and may only be given within acolor, 
Grayscale, Of Monochrome list. The optional wincolorlist allows per-window colorsto be 
specified. The default is black. 

BorderWidth pixels This variable specifies the width in pixels of the border surrounding all client window 
frames if ClientBorderwidth has not been specified. This value is also used to set the 
border size of windows created by twm (such as the icon manage’). T he default is 2. 

ButtonIndent pi xel s This variable specifies the amount by which titlebuttons should be indented on all sides. 
Positive values cause the buttons to be smaller than the window text and highlight area so 
that they stand out. Setting this and the Tit1leButtonBorderwidth variables to @ makes 
titlebuttons as tall and wide as possible. T he default is 1. 


ClientBorderWidth This variable indicates that border width of a window’s frame should be set to the initial 
border width of the window, rather than to the value of BorderWidth. 
Color { colors-list } This variable specifies a list of color assignments to be made if the default display is capable 


of displaying more than simple black and white Thecolors-list ismadeup of the 
following color variables and their values: 

DefaultBackground 

DefaultForeground 

MenuBackground 

MenuForeground 

MenuTitleBackground 

MenuTitleForeground 

MenuShadowColor 

PointerForeground 

PointerBackground 

The following color variables may also be given a list of window and color name pairs to 
allow per-window colors to be specified (see BorderColor for details): 

BorderColor 

IconManagerHighlight 

BorderTitleBackground 

BorderTitleForeground 

TitleBackground 
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ConstrainedMoveTime 
milliseconds 


Cursors { cursor-list } 


DecorateTransients 


DefaultBackground string 


TitleForeground 

IconBackground 

IconForeground 

IconBorderColor 

IconManagerBackground 

IconManagerForeground 

For example: 

Color 

{ 

MenuBackground "gray50" 

MenuForeground "blue" 

BorderColor "red" { "XTerm" "yellow" } 

TitleForeground "yellow" 

TitleBackground "blue" 

} 

All of these color variables may also be specified for the monochrome variable, allowing the 
same initialization file to be used on both color and monochrome displays. 

This variable specifies the length of time between button clicks needed to begin a 
constrained move peration. D ouble-clicking within this amount of time when invoking 

f .move will cause the window to be moved only in a horizontal or vertical direction. Setting 
this value to 0 will disable constrained moves. T he default is 400 milliseconds. 

This variable specifies the glyphs that twm should use for various pointer cursors. Each 
cursor may be defined athe from thecursor font or from two bitmap files. Shapes from 
the cursor font may be specified directly as 

@ cursorname “string" 

where cursorname is one of the cursor names listed below, and st ring isthenameof a 
glyph as found in the file 

<XRoot>/include/X11/cursorfont.h 

(without the xc prefix). If the cursor is to be defined from bitmap files, the following syntax 
is used instead: 

@ cursorname "i mage" "mask" 

Thei mage and mask strings specify the names of files containing the glyph image and mask 
in bitmap(1) form. T he bitmap files are located in the same manner as icon bitmap files. 
The following example shows the default cursor definitions: 


Cursors 

{ 

Frame "top_left_arrow" 
Title "top_left_arrow" 
Icon "top_left_arrow" 
IconMgr "top_left_arrow" 
Move "fleur" 

Resize "fleur" 

Menu "sb_left_arrow" 
Button "hand2" 

Wait "watch" 

Select "dot" 

Destroy "pirate" 


} 
This variable indicates that transient windows (those containing awm_TRANSIENT_FOR 
property) should havetitlebars. By default, transients are not reparented. 


This variable specifies the background color to be used for sizing and information windows. 
The default is white. 


DefaultForeground string 


DontIconif yByUnmapping 
{ win-list } 


DontMoveOf fF 


DontSqueezeTitle 
[{ win-list }] 


ForceIcons 
FramePadding pi xels 
Grayscale { colors } 
IconBackground string 


[{ win-list }] 


IconBorderColor string 
[{ win-list }] 


IconBorderWidth pi xels 
IconDirectory string 
IconFont string 


IconForeground string 


[{ win-list }] 
IconifyByUnmapping 
[{ win-list }] 


IconManagerBackground 
string [{ win-list }] 


IconManagerDontShow 
[{ win-list }] 
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This variable specifies the foreground color to be used for sizing and information windows. 
The default is black. 

This variable specifies a list of windows that should not be iconified window (as would be 
the caseif IconifyByUnmapping had been set). This is frequently used to force some 
windows to be treated as icons while other windows are handled by theicon manager. 
This variable indicates that windows should not be allowed to be moved off the screen. It 
can be overridden by the f. forcemove function. 

This variable indicates that titlebars should not be squeezed to their minimum size as 
described under squeezeTitle below. If the optional window list is supplied, only those 
windows will be prevented from being squeezed. 

This variable indicates that icon pixmaps specified in the tcons variable should override any 
client-supplied pixmaps. 

This variable specifies the distance betwen the titlebar decorations (the button and text) 
and the window frame. T he default is 2 pixds. 


This variable specifies a list of color assignments that should be made if the screen has a 
GrayScale default visual. See the description of colors. 

This variable specifies the background color of icons, and may only be specified inde of a 
Color, Grayscale, Of Monochrome list. The optional wi n-1ist iSalist of window names and 
colors so that per-window colors may be specified. See the Border -Color variable for a 
complete description of thewin-!ist. Thedefault is white. 

This variable specifies the color of the border used for icon windows, and may only be 
specified inside of acolor, Grayscale, OF Monochrome list. The optional wi n-list isalist 
of window names and colors so that per-window colors may be specified. See the 
BorderColor variable for a complete description of thewi n-1ist. The default is b1ack. 
This variable specifies the width in pixels of the border surrounding icon windows. The 
default is 2. 
This variable specifies the directory that should be searched if abitmap file cannot be found 
in any of the directories in the bitmapFilePath resource. 

This variable specifies the font to be used to display icon names within icons. The default is 
variable. 
This variable specifies the foreground color to be used when displaying icons, and may only 
be specified inside of acolor, Grayscale, Of Monochrome list. The optional win-1ist isa 
list of window names and colors so that per-window colors may be specified. See the 
BorderColor variable for a complete description of thewi n-1 ist. The default is b1ack. 

This variable indicates that windows should be iconified by being unmapped without 
trying to map any icons. T his assumes that the user will remap the window through the 
icon manager, the f.warpto function, or the Twmwindows menu. If the optional win-list is 
provided, only those windows will be iconified by smply unmapping. W indows that have 
both this and the 1conManager DontShow options set may not be accessible if no binding to 
the Twmwindows menu is set in the user's startup file. 


This variable specifies the background color to use for icon manager entries, and may only 
be specified inside of acolor, Grayscale, Of Monochrome list. The optional win-list isa 
list of window names and colors so that pe-window colors may be specified. See the 
BorderColor variable for a complete description of thewi n-1ist. The default is white. 


This variable indicates that the icon manager should not display any windows. If the 
optional win-1! ist isgiven, only those windows will not be displayed. This variable is used 
to prevent windows that are rarely iconified (such as xclock Or x1load) from taking up 
space in the icon manager. 
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IconManagerFont string 


IconManagerForeground 
string [{ win-list }] 


IconManagerGeometry 
string [ columns ] 


IconManagerHighlight 
string [{ win-list }] 


IconManagers 
{ iconmgr-list } 


This variable specifies the font to be used when displaying icon manager entries. T he default 
iS variable 
This variable specifies the foreground color to be used when displaying icon manager 
entries, and may be specified only inside of acolor, Grayscale, Of Monochrome list. The 
optional win-1ist iSalist of window names and colors so that per-window colors may be 
specified. See the Bordercolor variable for a complete description of thewin-list.The 
default is black. 


This variable specifies the geometry of the icon manager window. Thest ring argument is 
standard geometry specification that indicates the initial full size of the icon manager. T he 
icon manager window is then broken into columns pieces and scaled according to the 
number of entries in the icon manager. Extra entries are wrapped to form additional rows. 
The default number of columns is 1. 

This variable specifies the border color to be used when highlighting the icon manager entry 
that currently has the focus, and can only be specified inside of acolor, Grayscale, or 
Monochrome list. The optional win- | ist isalist of window namesand colors so that per- 
window colors may be specified. See the Border - Color variable for a complete description 
of thewin-list. The default is black. 

This variable specifies a list of icon managers to 

create Each item in thei conmgr-1ist has the following format: 


@ "win-name"[“iconname"] 





“geometry” columns 


where wi nname is thename of the windows that should be put into this icon manager, 
iconname isthenameof that icon manager window’sicon, geomet ry iSa standard geometry 
specification, and columns isthenumber of columns in thisicon manager as described in 
Icon-ManagerGeometry. For example: 

IconManagers 

{ 

"XTerm" "=300x5+800+5" 5 

"myhost" "=400x5+100+5" 2 

} 

Clients whose name or class is xTerm will have an entry created in the xTerm icon manager. 
Clients whose name was myhost would be put into the myhost icon manager. 


IconManagerShow{ win-l!ist } This variable specifies a list of windows that should appear in the icon manager. W hen used 


IconRegion geomstring 
vgrav hgrav gridwidth 
gridhei ght 


Icons { win-list } 


in conjunction with the rconManagerDontShow variable, only the windows in this list will be 
shown in theicon manager. 

This variable specifies an area on the root window in which icons are placed if no specific 
icon location is provided by theclient. Thegeomstring iSa quoted string containing a 
standard geometry specification. If more than one IconRegion line is given, icons will be 
put into the succeeding icon regions when the first is full. The vgrav argument should be 
either North Or South and is used to control whether icons are first filled in from the 

top or bottom of theicon region. Similarly, the hgrav argument should be either East or 
West and is used to control whether icons should be filled in from the left or from 

the right. Icons are laid out within the region in agrid with cells gridwi dth pixels wide and 
gridhei ght pixds high. 

This variable specifies a list of window names and the bitmap filenames that should be used 
as ther icons. For example, 

Icons 

{ 

"XTerm" "xterm.icon" 

"xfd" "xfd_icon" 

} 


Windows that match "xterm" and would not beiconified by unmapping would try to use 
the icon bitmap in the file xterm. icon. If ForceIcons is specified, this bitmap will be used 
even if the client has requested its own icon pixmap. 

InterpolateMenuColors This variable indicates that menu entry colors should be interpolated between entry 
specified colors. In this example, 
Menu "“mymenu" 
{ 
"Title" ("black":"red") f.title 
"entry1" f.nop 
"entry2" f.nop 
"entry3" ("white":"green") f.nop 
"entry4" f.nop 
"entry5" ("red":"white") f.nop 
} 
the foreground colorsfor “entry1” and “entry2” will be interpolated between black and 
white and the background colors between red and green. Similarly, the foreground for 
“entry4” will be halfway between white and red, and the background will be halfway 
between green and white. 


MakeTitle { win-list } This variable specifies a list of windows on which atitle-bar should be placed and is used 
to request titles on specific windows when NoTitle has bem set. 
MaxWindowSize string This variable specifies a geometry in which the width and height give the maximum size for 


a given window. T hisistypically used to restrict windows to the size of the scren. The 
default width is 32767— screen width. T he default height is 32767— screm height. 


MenuBackground string This variable specifies the background color used for menus, and can only be specified 
inside of a Color Or Monochrome list. The default is white. 

MenuFont string This variable specifies the font to use when displaying menus. T he default is variable. 

MenuForeground string This variable specifies the foreground color used for menus and can only be specified inside 
of aColor, Grayscale, Of Monochrome list. T he default is black. 

MenuShadowColor string This variable specifies the color of the shadow behind pull-down menus and can only be 


specified inside of a color, Grayscale, Of Monochrome list. The default is black. 
MenuTitleBackground string This variable specifies the background color for .tit1e entriesin menus, and can only be 
specified inside of acolor, Grayscale, Of Monochrome list. The default is white. 
MenuTitleForeground string This variable specifies the foreground color for f.tit1e entries in menus and can only be 
specified inside of a color OF Monochrome list. T he default is black. 








Monochrome { colors } This variable specifies a list of color assignments that should be made if the screen has a 
depth of 1. See the description of colors. 

MoveDelta pi xels This variable specifies the number of pixels the pointer must move before the f . move 
function starts working. Also see the f.deltastop function. T he default is zero pixds. 

NoBackingStore This variable indicates that twm’s menus should not request backing store to minimize 


repainting of menus. T hisis typically used with servers that can repaint faster than they can 
handle backing store. 

NoCaseSensitive This variable indicates that case should be ignored when sorting icon names in an icon 
manager. T his option is typically used with applications that capitalize the first letter of 
their icon name. 

NoDefaults This variable indicates that twm should not supply the default titlebuttons and bindings. 
This option should only be used if the startup file contains a completely new set of bindings 
and definitions. 

NoGrabServer This variable indicates that twm should not grab the serve when popping up menus and 
moving opaque windows. 
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NoHighlight [{ win-list }] 


NoIconManagers 


NoMenuShadows 


NoRaiseOnDeiconify 


NoRaiseOnMove 


NoRaiseOnResize 


NoRaiseOnWarp 


NoSaveUnders 


NoStackMode [{ win-list }] 


NoTitle [{ win-list }] 


NoTitleFocus 


NoTitleHighlight 
[{ win-list }] 


OpaqueMove 


Pixmaps { pixmaps } 


Priority priority 


RandomPlacement 


This variable indicates that borders should not be highlighted to track the location of the 
pointer. If the optional wi n- 1 ist iS given, highlighting will only be disabled for those 
windows. W hen the border is highlighted, it will be drawn in the current BorderColor. 

W hen the border is not highlighted, it will be stippled with a gray pattern using the current 
BorderTileForeground and BorderTileBack -ground Colors. 

This variable indicates that no icon manager should be created. 

This variable indicates that menus should not have drop shadows drawn behind them. This 
is typically used with slower servers because it speeds up menu drawing at the expense of 
making the menu slightly harder to read. 

This variable indicates that windows that are daiconified should not be raised. 

This variable indicates that windows should not be raised when moved. T his is typically 
used to allow windows to slide underneath each other. 

This variable indicates that windows should not be raised when resized. T hisis typically 
used to allow windows to be resized underneath each othe. 

This variable indicates that windows should not be raised when the pointer is warped into 
them with the t.warpto function. If this option is set, warping to an occluded window may 
result in the pointer ending up in the occluding window instead the desired window, which 
causes unexpected behavior with f.warpring. 

This variable indicates that menus should not request save-unders to minimize window 
repainting following menu sdection. It is typically used with displays that can repaint faster 
than they can handle save-unders. 

This variable indicates that client window requests to change stacking order should be 
ignored. If the optional win-! ist isgiven, only requests on those windows will beignored. 
This is typically used to prevent applications from rdentlessly popping thenselves to the 
front of the window stack. 
This variable indicates that windows should not havetitlebars. If the optional wi n- list is 
given, only those windows will not have titlebars. MakeTit1e may be used with this option 
to force titlebars to be put on specific windows. 
This variable indicates that twm should not set keyboard input focus to each window asit is 
entered. N ormally, twm sets the focus so that focus and key events from the titlebar and icon 
managers are delivered to the application. If the pointer is moved quickly and twm is slow to 
respond, input can be directed to the old window instead of the new. T his option is 
typically used to prevent this input lag and to work around bugs in older applications that 
have problems with focus events. 
This variable indicates that the highlight area of the titlebar, which is used to indicate the 
window that currently has the input focus, should not be displayed. If the optional wi n- 

list iSgiven, only those windows will not have highlight areas. T his and the squeezeTitle 
options can be set to substantially reduce the amount of screen space required by titlebars. 
This variable indicates that the f .move function should actually move the window instead of 
just an outline so that the user can immediately see what the window will look likein the 
new position. This option is typically used on fast displays (particularly if NoGrabServer is 
set). 

This variable specifies a list of pixmaps that define the appearance of various images. Each 
entry isa keyword indicating the pixmap to set, followed by a string giving the name of the 
bitmap file The following pixmaps may be specified: @ Pixmaps { TitleHighlight 
“gray1" } 

The default for TitleHighlight isto use an even stipple pattern. 

This variable sets twm’s priority. priority should bean unquoted, signed number (for 
example, 999). T his variable has an effect only if the server supports the SYN C extension. 
This variable indicates that windows with no specified geometry should be placed in a 
pseudorandom location instead of having the user drag out an outline. 
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ResizeFont string This variable specifies the font to be used for in the dimensions window when resizing 
windows. T he default is fixed. 
RestartPreviousState This variable indicates that twm should attanpt to use the ww_STATE property on client 


windows to tell which windows should be iconified and which should be left visible This is 
typically used to try to regenerate the state that the screen was in before the previous 
window manager was shutdown. 

SaveColor { colors-list } This variableindicates a list of color assignments to be stored as pixel values in the root 
window property _mzT_PRIoRITY_coLors. Clients may dect to preserve these values when 
installing thar own colormaps. N ote that use of this mechanism isa way for an application 
to avoid the “technicolor” problen, whereby useful screen objects such as window borders 
and titlebars disappear when a program’s custom colors are installed by the window 
manager. For example 
SaveColor 
{ 

BorderColor 

TitleBackground 

TitleForeground 

"red" 

"green" 

"blue" 

} 
This would place on the root window three pixel values for borders and titlebars, as well as 
the three color strings, all taken from the default colormap. 

ShowIconManager This variable indicates that the icon manager window should be displayed when twm is 
started. It can always be brought up using the f. showiconmgr function. 

SortIconManager This variable indicates that entries in the icon manager should be sorted alphabetically 
rather than by simply appending new windows to the end. 

SqueezeTitle This variable indicates that twm should attempt to use the sHare extension to make titlebars 

[{ squeeze-list }] occupy only as much screen space as they need, rather than extending all the way across the 
top of the window. T heoptional s queeze-1!ist may beused to control the location of the 
squeezed titlebar along the top of the window. It contains entries of the form: @ “name” 
justification numdenomwheename iSawindow name, justification iSeither left, 
center, OF right, and numand denomarenumbers specifying a ratio giving the relative 
position about which the titlebar is justified. T heratio is measured from left to right if the 
numerator is positive, and right to left if negative A denominator of @ indicates that the 
numerator should be measured in pixds. For convenience the ratio a/o isthesame as 1/2 
for center and -1/1 for right. For example 
SqueezeTitle { "XTerm" left @ @ "xtermi" left 1 3 "xterm2" left 2 3 
"oclock" center @ @ "emacs" right @ @ } 
The DontSqueezeTitle list can be used to turn off squeezing on certain titles. 

StartIconified This variable indicates that client windows should initially be left as icons until explicitly 

[{ win-list }] daconified by the user. If the optional wi n-!ist is given, only those windows will be 
started iconic. This is useful for programs that do not support an - iconic command-line 
option or resource. 














TitleBackground string This variable specifies the background color used in titleoars, and may only be specified 

[{ win-list }] inside of aColor, Grayscale, Of Monochrome list. The optional wi n-1ist iSalist of window 
names and colors so that per-window colors may be specified. T he default iswhite. 

TitleButtonBorderWidth This variable specifies the width in pixels of the border surrounding titleouttons. Thisis 

pixels typically set to @ to allow titlebuttons to take up as much space as possible and to not havea 


border. The default is 1. 
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TitleFont string 


TitleForeground string 
[{ win-list }] 


TitlePadding pixels 


UnknownIcon string 


UsePPosition string 


WarpCursor [{ win-list }] 


WindowRing { win-list } 


WarpUnmapped 


XorValue number 


Zoom [ count ] 


This variable specifies the font to be used for displaying window names in titlebars. The 
default is variable. 

This variable specifies the foreground color used in titlebars, and may only be specified 
inside of aColor, Grayscale, Of Monochrome list. The optional wi n-1ist iSalist of window 
names and colors so that per-window colors may be specified. T he default is black. 

This variable specifies the distance between the various buttons, text, and highlight areas in 
thetitlebar. T he default is 8 pixels. 

This variable specifies the filename of a bitmap file to be used as the default icon. This 
bitmap will be used as the icon of all clients that do not provide an icon bitmap and are not 
listed in the Icons list. 

This variable specifies whether or not twm should honor program-requested locations (given 
by the pPosition flag in the wm_NORMAL_HINTS propetty) in the absence of a user-specified 
position. Theargument st ri ng may have one of three values: off (the default), indicating 
that twm should ignore the program-supplied position; on, indicating that the position 
should be used; and non-zero, indicating that the position should used if it is othe than 
(0,0). The latter option is for working around a bug in older toolkits. 

This variable indicates that the pointer should be warped into windows when they are 
daiconified. If the optional wi n-1 ist is given, the pointer will only be warped when those 
windows are deiconified. 

This variable specifies a list of windows along which the f.warpring function cycles. 

This variable indicates that the f .warpto function should daiconify any iconified windows 
it encounters. T hisis typically used to make a key binding that will pop up a particular 
window (such as xmh) no matter where it is. T he default is for f .warpto to ignore iconified 
windows. 

This variable specifies the value to use when drawing window outlines for moving and 
resizing. T his should be set to a value that will result in a variety of distinguishable colors 
when exclusive or is used with the contents of the user's typical screen. Setting this variable 
to 1 often gives nice results if adjacent colors in the default colormap are distinct. By 
default, twm will attenpt to cause temporary lines to appear at the opposite end of the 
colormap from the graphics. 

This variable indicates that outlines suggesting movenent of a window to and from its 
iconified state should be displayed whenever a window is iconified or deiconified. The 
optional count argument specifies the number of outlines to be drawn. The default count 
iS8. 

















The following variables must be set after the fonts have been assigned, so it is usually best to put then at the end of the 
variables or at the beginning of the bindings sections: 


DefaultFunction function 


WindowFunction function 


BINDINGS 


This variable specifies the function to be executed when a key or button event is received for 
which no binding is provided. This is typically bound to f.nop, f.beep, of amMenu 
containing window operations. 

This variable specifies the function to execute when a window is sdected from the 
TwmWindows menu. If this variable is not set, the window will be deiconified and raised. 


After the desired variables have been set, functions may be attached titlebuttons and key and pointer buttons. Titlebuttons 
may be added from the left or right side and appear in the titlebar from left to right according to the order in which they are 
specified. K ey and pointer button bindings may be given in any orde. 


Titlebuttons’ specifications must include the name of the pixmap to use in the button box and the function to be invoked 
whe a pointer button is pressed within them: 


- 


Q LeftTitleButton "bit mapname"=function 


or 
@ RightTitleButton "bitmapname"=function 


Thebitmapname may refer to one of the built-in bitmaps (which are scaled to match Title -Font) by using the appropriate 
colon-prefixed name described earlier. 


K ey and pointer button specifications must give the modifiers that must be pressed, over which parts of the screen the 
pointer must be, and what function isto beinvoked. K eys are given as strings containing the appropriate keysym name; 
buttons are given asthe keywords Button1-Button5: @ "FP1" = modlist : context : function Button = modlist 
context : function 


Themodlist isany combination of the modifie name shift, control, lock, meta, mod1, mod2, mod3, mod4, OF mods (which 
may be abbreviated ass, c, 1, m, m1, m2, m3, m4, m5, respective y) separated by a vertical bar (|). Similarly, thecont ext is any 
combination of window, title, icon, root, frame, iconmgr, their first letters (iconmgr abbreviation ism), or ali, separated 
by avertical bar. The function is any of the ¢ keywords described in the following list. For example, the default startup file 
contains the following bindings: 
Button1 = : root : f.menu "TwmWindows" 
Button1 = m : window ; icon : f.function "move-or-lower" 
Button2 = m : window ; icon : f.iconify 
i) 
i] 


Button3 = m : window icon : f.function "move-or-raise" 


Button1 = : title : f.function "move-or-raise" 
Button2 = : title : f.raiselower 

Button1 = : icon : f.function "move-or-iconify" 
Button2 = : icon : f.iconify 

Button1 = : iconmgr : f.iconify 

Button2 = : iconmgr : f.iconify 


A user who wanted to be able to manipulate windows from the keyboard could use the following bindings: 











"F1" = : all : f.iconify 

"F2" =: a : f.raiselower 

"F3" = : all : f.warpring "next" 

"F4" = : all : f.warpto "xmh" 

"F5" = : all : f.warpto "emacs" 

"F6" =: a : f.colormap "next" 

"F7" =i a : f.colormap "default" 
"F20" = : all : f.warptoscreen "next" 
"Left" =m: all : f.backiconmgr 
"Right" =m | s_: all : f.forwiconmgr 


"Up" =m: all : f.upiconmgr 





"Down" =m {| S: all : f.downiconmgr 
twm provides many more window manipulation primitives than can be conveniently stored in atitlebar, menu, or set of key 
bindings. Although asmall set of defaults is supplied (unless the NoDefaults is specified), most users will want to havether 
most common operations bound to Key and button strokes. To do this, twm associates names with each of the primitives and 
provides user-defined functions for building higher level primitives and menus for interactively selecting among groups of 
functions. 
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User-defined functions contain the name by which they are referenced in calls to f. function and alist of other functions to 


execute 


For example, 


Function "move-or-lower" { f.move f.deltastop f.lower } 


Function "move-or-raise" { f.move f.deltastop f.raise } 


Function "move-or-iconify" { f.move f.deltastop f.iconify } 


Function "restore 


-colormap" { f.colormap "default" f.lower } 


The function name must be used in f. function exactly asit appears in the function specification. 


In the fo 





lowing descriptions, if the function is said to operate on the selected window, but is invoked from a root menu, the 


cursor will be changed to the Select cursor and the next window to receive a button press will be chosen: 


f 


h 


+ oh 


+> bh ot 
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h 


+h 


h 


+h 


+h 


String 


.autoraise 


. backiconmgr 


. beep 
.bottomzoom 


.circledown 
-circleup 


.colormap string 


.deiconify 


- delete 


.deltastop 


. destroy 


. downiconmgr 


-exec string 


. focus 


Thisis an abbreviation for f.exec string. 

This function toggles whether or not the sdected window is raised whenever entered by the 
pointer. See the description of the variable AutoRaise. 

This function warps the pointer to the previous column in the current icon manager, 
wrapping back to the previous row if necessary. 


This function sounds the keyboard bal. 


This function is similar to the f. ful1zoom function, but resizes the window to fill only the 
bottom half of thescreen. 

This function lowers the topmost window that occludes another window. 

This function raises the bottommost window that is occluded by another window. 

This function rotates the colormaps (obtained from the wm_CoLoRMAP_WINDOwsS property on 
the window) that twm will display when the pointer isin this window. T heargument 
string may haveoneof the following values: next, prev, and default. It should be noted 
here that in general, the installed colormap is determined by keyboard focus. A pointer- 
driven keyboard focus will install a private colormap upon entry of the window owning the 
colormap. U sing the click-to-type modd, private colormaps will not be installed until the 
user clicks on the target window. 

This function deiconifies the sdected window. If the window is not an icon, this function 
does nothing. 

This function sends the wm_DELETE_WINDOw message to the selected window if the client 
application has requested it through thewm_protococs window propety. The application is 
supposed to respond to the message by removing the indicated window. If the window has 
not requested wM_DELETE_WINDOow messages, the keyboard bel will be rung, indicating that 
the user should choose an alternative method. N ote thisis very different from f. destroy. 
The intent hereisto ddetea single window, not necessarily the entire application. 

This function allows a user-defined function to be aborted if the pointer has been moved 
more than MoveDelta pixels. See the example definition given for Function "move-or- 
raise" at the beginning of the section. 

This function instructs the x server to close the display connection of the client that created 
the sdected window. This should only be used as a last resort for shutting down runaway 
clients. See also f. delete. 

This function warps the pointer to the next row in the current icon manger, wrapping to 
the beginning of the next column if necessary. 

This function passes the argument string to /bin/sh for execution. In multiscreen mode 
ifstring starts anew x client without giving a display argument, the client will appear on 
the screen from which this function was invoked. 

This function toggles the keyboard focus of the server to the selected window, changing the 
focus rule from pointer-driven if necessary. If the selected window already was focused, this 
function executes an f.unfocus. 

















. forcemove 


. forwiconmgr 


- fullzoom 


. function string 


.hbzoom 
. hideiconmgr 


-horizoom 


»htzoom 
»hzoom 
-iconify 


. identify 


. lefticonmgr 


. Leftzoom 


. Lower 


-menu string 


. move 


.nexticonmgr 


nop 


. previconmgr 


-priority string 


-quit 


.raise 


. raiselower 
-refresh 


-resize 


restart 


.righticonmgr 


This function is like f .move except that it ignores the Dontmoveorff variable 


This function warps the pointer to the next column in the current icon manager, wrapping 
to the beginning of the next row if necessary. 


This function resizes the sdected window to the full size of the display or else restores the 
original size if the window was already zoomed. 


This function executes the user-defined function whose name is specified by the argument 
string. 
This function is a synonym for f.bottomzoom. 

This function unmaps the current icon manage. 


This variable is similar to the f . zoom function except that the sdected window is resized to 
the full width of the display. 


This function is a synonym for f.topzoom. 

This function is a synonym for f.horizoom. 

This function iconifies or deiconifies the selected window or icon, respectivdly. 

This function displays a summary of the name and geometry of the selected window. If the 
server supports the sync extension, the priority of the client owning the window is also 
displayed. Clicking the pointer or pressing a key in the window will dismiss it. 

This function is similar to  .backiconmgr except that wrapping does not change rows. 
This variable is similar to the f . bot tomzoom function but causes the selected window to be 
resized only on the left half of the display. 

This function lowers the sdected window. 

This function invokes the menu specified by the argument st ri ng. Cascaded menus may be 
built by nesting calls to .menu. 

This function drags an outline of the selected window (or the window itself if the 
OpaqueMove variable is set) until the invoking pointer button is rdeased. D ouble-clicking 
within the number of milliseconds given by constrainedMoveTime warps the pointer to the 
center of the window and constrains the move to be either horizontal or vertical, depending 
on which grid line is crossed. To abort a move, press another button before rdeasing the 
first button. 

This function warps the pointer to the next icon manager containing any windows on the 
current or any succeeding screen. 

This function does nothing and is typically used with the Default - Function or 
WindowFunct ion variables or to introduce blank lines in menus. 

This function warps the pointe to the previous icon manager containing any windows on 
the current or preceding screens. 

This function sets the priority of theclient owning the selected window to the numeric 
value of the argument st ri ng, which should bea signed integer in double quotes (for 
example, “999”). T his function has an effect only if the server supports the sync extension. 
This function causes twm to restore the window's borders and exit. If twm is the first client 
invoked from xam, this will result in a server reset. 

This function raises the sd ected window. 

This function raises the sdected window to the top of the stacking order if it is occluded by 
any windows; otherwise, the window is lowered. 

This function causes all windows to be refreshed. 

This function displays an outline of the sdected window. Crossing a border (or setting 
AutoRelativeResize) will cause the outline to begin to rubber band until the invoking 
button is released. To abort a resize, press another button before releasing the first button. 
This function kills and restarts twm. 


This function is similar to f .nexticonmgr except that wrapping does not change rows. 
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rightzoom 


. saveyourself 


. showiconmgr 


-sorticonmgr 


- title 


. topzoom 


.unfocus 


. upiconmgr 


.vlzoom 
.vrzoom 


-warpring string 


-warpto string 


-warptoiconmgr string 


.warptoscreen string 


.winrefresh 


.Zoom 


MENUS 


Functions may be grouped and interactively selected using pop-up (when bound to a pointer button) or pull-down (when 
associated with a titlebutton) menus. Each menu specification contains the name of the menu as it will be referred to by 
f.menu, optional default foreground and background colors, the list of item names and the functions they should invoke, 
and optional foreground and background colors for individual items: 


This variable is similar to the f . bot tomzoom function except that the selected window is 
only resized to the right half of the display. 

This function sends a wM_SAVEYOURSELF message to the selected window if it has requested 
the message in its wm_PROTOCOLS window property. Clients that accept this message are 
supposed to checkpoint all states associated with the window and update the wm_commanp 
property as specified in the rcccm. If the sdected window has not bem sdected for this 
message, the keyboard bell will be rung. 

This function maps the current icon manager. 

This function sorts the entries in the current icon manage alphabetically. See the variable 
SortIconManager. 

This function provides a centered, unselectableitem in amenu definition. It should not be 
used in any other context. 

This variable is similar to the f . bot tomzoom function except that the selected window is 
only resized to the top half of the display. 

This function resets the focus back to pointer-driven. This should be used when a focused 
window is no longer desired. 

This function warps the pointer to the previous row in the current icon manager, wrapping 
to the last row in the same column if necessary. 

This function is a synonym for f.1eftzoom. 

This function is asynonym for f.rightzoom. 

This function warps the pointer to the next or previous window (as indicated by the 
argument st ring, which may be "next" or "prev") specified in the windowRing variable 
This function warps the pointer to the window that has anameor class that matches 
string. If the window is iconified, it will be deiconified if the variable warpUnmapped is set 
or dse ignored. 
This function warps the pointer to the icon manager entry associated with the window 
containing the pointer in theicon manager specified by the argument st ring. If string is 
empty (that is, ""), the current icon manager is chosen. 

This function warps the pointer to the screen specified by the argument string.string 
may bea number (such as “o” or “1”), the word “next” (indicating the current screen plus 
1, skipping over any unmanaged screens), the word “back” (indicating the current screen 
minus 1, skipping over any unmanaged screans), or the word “ prev" (indicating the last 
screen visited. 

This function is similar to the f. refresh function except that only the sdected window is 
refreshed. 

This function is similar to the ¢. ful1zoom function, except that only the height of the 
selected window is changed. 











Menu "menuname"[("deffore":"defback") ] { stringl [("forel":"backn")] functionl string2 


[("fore2":"backn")] function2 


~..StringN [("foreN":"backN")] functionN } 


The menuname is case-sensitive. T he optional deffore and defback arguments specify the foreground and background colors 
used on acolor display to highlight menu entries. The string portion of each menu entry will be the text that will appear in 
the menu. The optional fore and back arguments specify the foreground and background colors of the menu entry when the 
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pointer is not in the entry. T hese colors will only be used on acolor display. T he default is to use the colors specified by the 
MenuForeground and MenuBackground variables. T he function portion of the menu entry is one of the functions, including 
any user-defined functions, or additional menus. 


Thee is a specia menu named Twmwindows that contains the names of all of the client and twm-supplied windows. Sdecting 
an entry will cause the windowFunction to be executed on that window. If windowFunction hasn't been set, the window will 
be deiconified and raised. 

ICONS 


twm supports several different ways of manipulating iconified windows. The common pixmap-and-text style may be laid out 
by hand or automatically arranged as described by the rconRegion variable. In addition, a terse grid of icon names, called an 
icon manage’, provides a more efficient use of screen space as wal as the ability to navigate among windows from the 
keyboard. 


An icon manager is a window that contains names of selected windows or all windows currently on the display. In addition 
to the window name, a small button using the default iconify symbol will be displayed to the left of the name when the 
window isiconified. By default, clicking on a entry in the icon manager performs +f. iconify. To change the actions taken 
in theicon manager, use the iconmgr context when specifying button and keyboard bindings. 


If you move the pointer into the icon manager, the keyboard focusis also directed to the indicated window (setting the focus 
explicitly or else sending synthetic events NoTitleFocus is set). Using the f. upiconmgr, f.downiconmgr, f.lefticonmgr, 
and f .righticonmgr functions, the input focus can be changed between windows directly from the keyboard. 


BUGS 
The resource manager should have been used instead of all of the window lists. 
The IconRegion variable should take alist. 


D ouble-clicking very fast to get the constrained move function will sometimes cause the window to move, even though the 
pointer is not moved. 


If IconifyByUnmapping iS on and windows are listed in IconManagerDontShow but not in Dont Iconif yByUnmapping, they 
may be lost if they are iconified and no bindings to t.menu * Twmwindows” Or f.warpto are setup. 


FILES 


$HOME/.twmrc.<screen number> 
$HOME/.twmrc 
<XRoot>/1ib/X11/twm/system. twmrc 


ENVIRONMENT VARIABLES 


DIsPLay This variableis used to determine which x server to use. It is also set during f. exec so that programs come up on 
the proper screen. 


HOME This variable is used as the prefix for files that begin with a tilde and for locating the twm startup file. 


SEE ALSO 


x(1), Xserver(1), xdm(1), xrdb(1) 


AUTHORS 


Tom LaStrange, Solbourne C omputer; Jim Fulton, MIT X Consortium; Steve Pitschke, Stardent Computer; Kath Packard, 
MIT X Consortium; D ave Payne Apple Computer. 


SEE ALSO 
x(1), Xserver(1), x 


X Verdon 11 Release 6 
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txt2gcal 


txt2gcal— Creates a verbatim gcal resource filefrom atext file 


SYNOPSIS 


txt2gcal [ --help | --version ] ; [ Text-file | - ][Date-part ] 


DESCRIPTION 


txt2gcal isa program that creates a verbatim gcai resourcefile from a text file If not ext-file or - argument is given, the 
program reads and processes all input received from the standard input channel. If nodate- part argument is given, 
txt2gcal creates ao for the date part. All results are always shown on the standard output channd. An exit status of @ means 
all processing is successfully done; any other value means an error has occurred. 


OPTIONS 
--help Print a usage message listing all available options, then exit successfully. 
--version Print the version number, then exit successfully. 

COPYRIGHT 


Copyright© 1996 Thomas Esken. This software doesn’t claim completeness, correctness, or usability. On principle, | will not 
be liable for any damages or losses (implicit or explicit), which result from using or handling my software. If you use this 
software, you agree without any exception to this agreanent, which binds you legally. 


txt2cal is free software and distributed under the tems of the GN U General Public License; published by the Free Software 
Foundation; version 2 or (at your option) any later version. 


Any suggestions, improvenents, extensions, bug reports, donations, proposals for contract work, and so forth are wdcome. If 
you like this tool, |’d appreciate a postcard from you! 


Enjoy it =8°) 
AUTHOR 


Thomas Esken (esken@uni-muenster.de) 
m H agenfdd 84 

D-48147 Munster; Germany 

Phone: +49 251 232585 


SEE ALSO 
gcal(1), tca1(1) 
16 July 1996 


ul 


ul— Do underlining 


SYNOPSIS 
ul [-i] [-t terminal] [name ...] 
DESCRIPTION 


u1 reads the named files (or standard input if noneare given) and translates occurrences of underscores to the sequence that 
indicates underlining for the terminal in use, as specified by the environment variable Term . The file /etc/termcap is read to 
determine the appropriate sequences for underlining. If the terminal is incapable of underlining but is capable of a standout 


unexpand 


mode, then that is used instead. If the terminal can overstrike or handles underlining automatically, u1 degenerates to 
cat(1). If the terminal cannot underline underlining is ignored. 


The following options are available: 


“i Underlining is indicated by a separate line containing appropriate dashes -; this is useful when you want to 
look at the underlining which is present in an nroff output stream on aCRT terminal. 


-t terminal Overrides the terminal type specified in the ewvironment with terminal. 


ENVIRONMENT 
The following environment variable is used 


TERM Relates a tty device with its device capability description; see termcap(5). TERM is set at login time, either 
by the default terminal type specified in /etc/ttys or as s& during the login process by the user in the 
login file, see setenv(1). 


SEE ALSO 


man(1), nroff(1), colert(1) 


BUGS 


nroff usually outputs a series of backspaces and underlines intermixed with the text to indicate underlining. N o attempt is 
made to optimize the backward motion. 


HISTORY 
The ul command appeared in BSD 3.0. 
BSD 4, 6 June1993 


unexpand 
unexpand— C onvert spaces to tabs 

SYNOPSIS 
unexpand [-tabl[,tab2[,...]]] [-t tabl[,tab2[,...]]] [-a][--tabs=tabl[,tab2[,...]]] 
[--all] [--help] [--version] [file...] 

DESCRIPTION 


This manual page documents the GN U version of unexpand. unexpand writes the contents of each given file or the standard 
input if none are given or when a filenamed - is given, to the standard output, with strings of two or more space or tab 
characters converted to as many tabs as possible followed by as many spaces as are needed. By default, unexpand converts 
only initial soaces and tabs (those that precede all characters that aren’t spaces or tabs) on each line It preserves backspace 
characters in the output; they decrement the column count for tab calculations. By default, tabs are set at every 8th column. 


OPTIONS 

-, -t, --tabs tabl[,tab2[,...]] lf only onetab stop isgiven, se the tabst ab1 spaces apart instead of the default s. 
Otherwise, set thetabs at columnst ab1, tab2, and so on (numbered from a) and 
leave spaces and tabs beyond the tab stops given unchanged. If the tab stops are 
specified with the -t or - -tabs option, they can be separated by blanks as well as by 
commas. T his option implies the -a option. 

-a, --all Convert all strings of two or more spaces or tabs, not just initial ones, to tabs. 

--help Print a usage message and exit with a non-zero status. 

--version Print version information on standard output, then exit. 


GNU Tet Utilitie 
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unig— Remove duplicate lines from a sorted file 

SYNOPSIS 
uniq [-cdu] [-f skip-fields] [-s skip-chars] [-w check-chars] [-#skip-fields] 
[t+#skip-chars] [--count] [--repeated] [--unique] [--skip-fields=skip-fields] 
[--skip-chars=skip-chars] [--check-chars=check-chars] [--help] [--version] 


[infile] [outfile] 


DESCRIPTION 


This manual page documents the GN U version of unig. unig prints the unique lines in a sorted file, discarding all but one of 
arun of matching lines. It can optionaly show only lines that appear exactly once or lines that appear more than once. uniq 
requires sorted input because it compares only consecutive lines. 


If the output file is not specified, unig writes to the standard output. If the input file is not specified, it reads from the 


standard input. 
OPTIONS 


-u, --unique 
-d, --repeated 
-c, --count 


-number, -f, 
--skip-fields=number 


tnumber, -s, 
- -skip-chars=number 


-W, 
- - check -chars=number 
--help 


--version 


unshar 


unshar— Unpack a shar file 


SYNOPSIS 


unshar [ -d directory ] [ 


DESCRIPTION 


Only print unique lines 
Only print duplicate lines 
Print the number of times each line occurred along with the line 


In this option, number isan integer representing the number of fields to skip over 
before checking for uniqueness. The first number fidds, along with any blanks 
found beforenumber fields is reached, are skipped over and not counted. Fidds are 
defined as astrings of nonspace, nontab characters that are separated from each 
other by spaces and tabs. 


In this option, number isan integer representing the number of characters to skip 
over before checking for uniqueness. The first number characters, along with any 
blanks found beforenumber characters is reached, are skipped over and not counted. 
If you use both the fidd and character skipping options, fields are skipped over first. 


Specify the number of characters to compare in the lines, after skipping any specified fields 
and characters. N ormally, the entire remainder of the lines are compared. 


Print a usage message and exit with a non-zero status. 
Print version information on standard output, then exit. 


GNU Tet Utilitie 


-c J[-e | -E exit_line ] [file ... ] 


unshar Scans mail messages looking for the start of a shal archive It then passes the archive through a copy of the shell 
to unpack it. It will acceot multiple files. If no files are given, standard input is used. This manual page reflects unshar 


version 4.0. 


updatedb 
OPTIONS 


O ptions havea oneletter version starting with - or along version starting with - -. The exceptions are - -help and - - 
version, which don’t havea short version. 


--version Print the version number of the program on standard output, then immediatdy exit. 

--help Print ahap summary on standard output, then immediately exit. 

-d DI RECTORY Change directory to DI RECTORY 

--directory=DI RECTORY before unpacking any files. 

-c --overwrite Passed as an option to the shar file M any shdl archive scripts (including those produced by 
shar 3.40 and newer) accept a -c argument to indicate that existing files should be 
overwritten. 

-e --exit-0 This option exists mainly for people who collect many shdl archives into a single mail 


folder. W ith this option, unshar isolates each different shal archive from the others that 
have been put in the same file, unpacking each in turn, from the beginning of the file 
towards its end. Its proper operation relies on the fact that many shar files are terminated 
by an exit @ at the beginning of aline 
Option -e isinternally equivalent to -E "exit 0". 
-E STRING This option works like -e, but it allows you to specify the string that separates archives 
--split-at=STRI NG if exit o isn’t appropriate. For example noticing that most . signatures havea - - 
on aline right before them, one can sometimes use - - split -at=- - for splitting shal 
archives that lack the exit line at end. T hesignature will then be skipped altogether with 
the headers of the following message 


SEE ALSO 


shar(1) 


DIAGNOSTICS 
Any message from the shell may be displayed. 


AUTHORS 


Michad M auldin at Carnegie M ellon U niversity, Guido van Rossum at CWI, Amsterdam (guido@mevax), Bill D avidsen 
(davidsen@sixhub. uuxp), Warren Tucker (wht%sn4hgf@gatech.edu) 

Richard H. Gumpertz (rhgacrs.com), and Colas N ahaboo (colas@avahi.inria.fr). M an pages by J an Djfrv 
(jhd@irfu.se). 


12 August 1990 


updatedb 


updatedb— U pdate a filename database 


SYNOPSIS 


updatedb [options ] 


DESCRIPTION 


This manual page documents the GN U version of updatedb, which updates filename databases used by GN U locate. The 
filename databases contain lists of files that were in particular directory trees when the databases were last updated. The 
filename of the default database is determined when locate and updatedb are configured and installed. The frequency with 
which the databases and the directories for which they contain entries are updated depends on how often updatedb isrun, 
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and with which arguments. In networked environments, it often makes sense to build a database at the root of each 
filesystem, containing the entries for that filesystem. To prevent thrashing the network, updatedb is then run for each 
filesystem on the fileserver where that filesystem ison alocal disk. Users can select which databases locate searches using an 
environment variable or command-line option; see locate(1L). D atabases can not be concatenated together. The filerame 
database format changed starting with GNU fina and locate version 4.0 to allow machines with different byte orderings to 
share the databases. The new GNU locate can read both the old and new database formats. H owever, old versions of 
locate and find produce incorrect results if given a new-format database. 


OPTIONS 
--localpaths='pathl path2...' N onnetwork directories to put in the database. D efault is /. 
--netpaths='pathl path2...' N etwork (NFS, AFS, RFS, and so on) directories to put in the database D efault is 
none. 
--prunepaths='pathl path2...' Directories to not put in the database, which would otherwise be put there. D efault 
IS/tmp /usr/tmp /var/tmp /afs 
--output=dbfile T he database file to build. D efault is system-dependent, but typically /usr/local/ 
var/locatedb 
--netuser=us er The user to search network directories as, using su(1). D efault is daemon. 
--old-format Create the database in the old format instead of the new one. 
--version Print the version number of updatedb and exit. 
--help Print asummary of the options to updatedb and exit. 
SEE ALSO 


find(1L), locate(1L), locatedb(5L), xargs(1L) Finding Files(onlinein info, or printed) 


uptime 
uptime—T ell how long the system has been running 


SYNOPSIS 


uptime 


DESCRIPTION 


uptime gives a one line display of the information that follows it: the current time how long the system has been running, 
how many users are currently logged on, and thesystem load averages for the past 1, 5, and 15 minutes. 


This is the same information contained in the header line displayed by w(1). 


FILES 
/var/run/utmp Information about who is currently logged on 
/proc Process information 

AUTHORS 


uptime was written by Larry Greenfidd (greenfie@gauss.rutgers.edu) and M ichad K. Johnson 
(johnsonm@sunsite.unc.edu). 


SEE ALSO 
ps(1), top(1), utmp(5), w(1) 
Cohedve Systems 26 January 1993 
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userlist— User listing of who's on your system 


SYNOPSIS 


userlist 


DESCRIPTION 


This program simply gives you a listing of who is connected to your system. It is used primarily in the sorted listing that 
utilitizes the same method of display for amore uniform output between systems. It also made more sense to do it this way 
instead of having jumbled up display listings in sorted finger displays. Besides, it made more sense to do this than use 
finger. :) 


This program functions with the same types of things in mind that cfingerd does. If the user has a .nofinger file, his or her 
username will not be displayed in the user listing. 


Example output is shown as 


Username Real Name Idletime TTY Remote console username I'm real ... 9d 23:59 0 
(remote.site.com) 


where it would display the user’s login name, the user’s real name, the user's idle time given in the format “dd hh: mm”, the 
TTY, and the remote location (or where the user is telnetting from). 


If the username is more than a certain number of characters, the program will not search for ther information in the passwd 
file because it may be too long. Besides, it checks getpwnam, anyway. 


CONTACTING 


If you like this program, have any suggestions on how it could be modified, or have bug reports, please write to 
khollis@bitgate.com. 


Your continued public domain support is appreciated! T hanks. 
SEE ALSO 
cfingerd.conf(5), cfingerd(8), finger(1) 
Userlig¢ 0.0.1, 26 August 1995 


uuCcp 


uucp— UN1IX-to-UNIX copy 
SYNOPSIS 


uucp [ options ] source-file destination-file 


uucp [ options ] source-file... destination-directory 


DESCRIPTION 


The uucp command copies files between systems. Each file argument is either a pathname on the local machine or is of the 
form 


system! path 


which is interpreted as bang on aremote system. In thefirst form, the contents of the first file are copied to the second. In 
the second form, each source fileis copied into the destination directory. 
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A file be transferred to or from system2 viasysteml by using 


systeml !system2!path 


Any pathname that does not begin with / or ~ will be appended to the current directory (unless the -w or - -noexpand option 
is used); this resulting path will not necessarily exist on a remote system. A pathname beginning with a simple ~ starts at the 
uucp public directory; a pathname beginning with “name starts at the home directory of thenamed user. T he ~ isinterpreted 
on the appropriate systen. N ote that some shells will interpret a simple ~ to the local home directory before uucp sees it; to 


avoid this, the ~ must be quoted. 


Shel metacharacters ? * [ ] areinterpreted on the appropriate system, assuming they are quoted to prevent the shal from 


interpreting them first. 


The copy does not take placeimmediatey, but is queued up for the uucico(8) daemon; thedaamon is started immediately 
unless the -r or - -nouucico switch is given. In any case, the next time the remote system is called, the file(s) will be copied. 


The following options may be given to uucp. 


OPTIONS 
-C, --nocopy 
-C, --copy 


-d, --directories 
-f, --nodirectories 


-g grade, --grade grade 


-m, --mail 


-n user, --notify user 
-r, --nouucico 


-j, -jobid 


-W, - -noexpand 
-x type, --debug type 


-I file, --config file 


-v, --version 
--help 


FILES 


Do not copy local source files to the spool directory. If they are renoved before being 
processed by the uucico(8) daenon, the copy will fail. The files must be readable by the 
uucico(8) daemon, and by the invoking user. 


Copy local source files to the spool directory. T hisis the default. 

Create all necessary directories when doing the copy. T hisis the default. 

If any necessary directories do not exist for the destination path, abort the copy. 

Se the grade of the file transfer command. J obs of a higher grade are executed first. G rades 
run@... 9A... Za... zfromhigh to low. 

Report completion or failure of the file transfer by mai1(1). 

Report completion or failure of the file transfer by mai1(1) to the named user on the remote 
system. 

Do not start uucico(8) daemon immediately; meray queue up the file transfer for later 
execution. 


Print} obid on standard output. The job may be later canceled by passing thej obi d to the 
-k switch of uustat(1). It is possible for some complex operations to produce more than 
onej obi d, in which case, each will be printed on a separate line For example, 

uucp sysl!"userl/filel sys2!~user2/file2 “user3 

will generate two separate jobs, one for the system sys1 and one for the system sys2. 

Do not prepend remote relative pathnames with thecurrent directory. 

Turn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 
Only abnormal, config, spooldir, and execute are meaningful for uucp. M ultiple types 
may be given, separated by commas, and the - -debug option may appear multiple times. A 
number may also be given, which will turn on that many types from the foregoing list; for 
example, --debug 2iS equivalent to - -debug abnormal, chat. 

Sé configuration file to use. This option may not be available, depending upon how uucp 
was compiled. 

Report version information and exit. 

Print ahap message and exit. 





The filenames may be changed at compilation time or by the configuration file, so these are only approximations. 


uuencode 


/usr/lib/uucp/config Configuration file 
/usr/spool/uucp uucp Spool directory 
/usr/spool/uucp/Log uucp logfile 
/usr/spool/uucppublic Default uucp public directory 
SEE ALSO 
mail(1), uux(1), uustat(1), uucico(8) 
BUGS 


Some of the options are dependent on the capabilities of the uucico(8) daemon on the remote system. 
The -n and -m switches do not work when transferring a file from one remote systen to another. 
File modes are not preserved, except for the execute bit. T he resulting file is owned by the uucp user. 


AUTHOR 


lan Lance T aylor (ian@airs.com) 
Taylor UUCP 1.05 


uuencode 


uuencode— Encode a binary file 
uudecode —D ecodea file created by uuencode 


SYNOPSIS 


uuencode [-m] [ file ] name 


uudecode [-o outfile] [ file ]... 


DESCRIPTION 


uuencode and uudecode are used to transmit binary files over transmission mediums that do not support other than simple 
ASCII data. 


uuencode readsfile (or by default the standard input) and writes an encoded version to the standard output. The encoding 
uses only printing ASCII characters and includes the mode of the file and the operand name for useby uudecode. If name iS / 
dev/stdout, the result will be written to standard output. By default, the standard uu encoding format will be used. If the 
option -mis given on the command line base64 encoding is used instead. 


uudecode transforms uuencoded files (or by default, the standard input) into the original form. T he resulting file is named 
name (OF outfile if the -o option is given) and will havethe mode of the original file except that setuid and execute bits 
are not retained. If outfile or name iS /dev/stdout, the result will be written to standard output. uudecode ignores any 
leading and trailing lines. The program can automatically decide which of the supported encoding schanes are used. 


EXAMPLES 


The following example packages up a source tree, compresses it, uuencodes it, and mails it to a user on another system. 
When uudecode isrun on thetarget system, the file src_tree.tar.Zz will be created, which may then be uncompressed and 
extracted into the original tree. 


tar cf - src_tree | compress | uuencode src_tree.tar.Z | mail sys1!sys2!user 
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SEE ALSO 


compress(1), mail(1), uucp(1), uuencode(5) 


STANDARDS 
This implementation is compliant with P1003.2b/D 11. 


BUGS 


If more than one file is given to uudecode and the -o option isgiven or morethan onename in the encoded files is the same, 
the result is probably not what is expected. 


The encoded form of the file is expanded by 37 percent for uu encoding and by 35 percent for base64 encoding (3 bytes 
become 4 plus control information). 


HISTORY 


The uuencode command appeared in BSD 4.0. 


uustat 


uustat— uucp Status inquiry and control 


SYNOPSIS 


uustat -a 
uustat --all 


uustat [ -eKRiMNQ ][-sS system ] [ -wU user ] [ -cC command ] [ -oy hours ] 

[ -B lines ] [ --executions ][--kill-all ][--rejuvenate-all ][--prompt ][--mail ] 
[--notify ][--no-list ][--system system ] [ --not-system system ] [ --user user ] 
[--not-user user ] [ --command command ] [ --not-command command ] 

[ --older-than hours ] [ --younger-than hours ] [ --mail-lines lines ] 

uustat [ -kr jobid ] [ --kill jobid ] [ --rejuvenate jobid ] 


uustat -q [ -sS system ] [ -oy hours ] [ --system system ] [ --not-system system ] 
[--older-than hours ] [ --younger-than hours ] 


uustat --list [ -sS system ] [ -oy hours ] [ --system system ] 
[ --not-system system ] [ --older-than hours ] [ --younger-than hours ] 


uustat -m 
uustat --status 
uustat -p 


uustat --ps 


DESCRIPTION 


The uustat command can display various types of status information about the UUCP system. It can also be used to cance 
or rejuvenate requests made by uucp(1) or uux(1). 


By default uustat displays all jobs queued up for the invoking user, as if given the - -user option with the appropriate 
argument. 


uustat 567 


If any of the -a, --all, -e, --executions, -s, --system, -S,--not-system, -u, --user, -U, --not-user, -c, --command, -C 


--not-command, -o, --older-than, -y, --younger-than options are given, then all jobs that match the combined specifica- 


tions are displayed. 


The -k or - -kill-a11 option may be used to kill off a sdected group of jobs, such asall jobs more than seven days old. 


OPTIONS 


The following options may be given to uustat. 


-a, --all 


-e, --executions 


-s system, 


-S system, 
--not-system system 


-u user, --user user 
-U user, --not-user user 
-c command, 


--command command 


-C command, 
--not-command command 


-o hours, 
--older-than hours 


-y hours, 
--younger-than hours 


-k jobid, --kill j obid 


-r jobid, 
--rejuvenate j obid 


--system system 


List all queued file transfer requests. 

List queued execution requests rather than queued file transfer requests. Q ueued execution 
requests are processed by uuxqt(8) rather than uucico(8). Q ueued execution requests may 
be waiting for some file to be transferred from a remote system. T hey are created by an 
invocation of uux(1). 

List all jobs queued up for thenamed system. T hese options may be specified multiple 
times, in which case all jobs for all the systems will be listed. If used with --1ist, only the 
systems named will be listed. 

List all jobs queued for systems other than the one named. T hese options 

may be specified multiple times, in which case no jobs from any of the specified systems will 
be listed. If used with -- list, only the systems not named will be listed. T hese options 
may not be used with -s or --system. 

List all jobs queued up for the named user. T hese options may be specified multiple times, 
in which case all jobs for all the users will be listed. 

List all jobs queued up for users other than the one named. T hese options may be specified 
multiple times, in which case no jobs from any of the specified users will be listed. T hese 
options may not be used with -u or --user. 

List all jobs requesting the execution of thenamed command. If command iS ALL thiswill 
list all jobs requesting the execution of some command (as opposed to simply requesting a 
file transfer). These options may be specified multiple times, in which case all jobs 
requesting any of the commands will be listed. 

List all jobs requesting execution of some command other than thenamed 

command, or, if command iSALL, list all jobs that simply request a file transfer (as opposed 
to requesting the execution of some command). T hese options may be specified multiple 
times, in which case, no job requesting one of the specified commands will be listed. T hese 
options may not be used with -c or - - command. 

List all queued jobs older than the given number of hours. If used with - -1ist, only 
systems whose oldest job is older than the given number of hours will be listed. 

List all queued jobs younger than the given number of hours. If used with - -1ist, 

only systems whose oldest job is younger than the given number of hours will be 

listed. 

Kill the named job. Thejob ID is shown by the default output format, as well as by the - j 
or --jobid option to uucp(1) or uux(1). A job may only bekilled by the user who created 
the job, or by the UUCP administrator or the superuser. The -k or - -kil1 options may be 
used multiple times on the command line to kill several jobs. 

Rejuvenate the named job. This will mark it as having been invoked at the current 

time, affecting the output of the -o, -- older-than, -y, Of - - younger -than options and 
preserving it from any automated cleanup daemon. The job ID is shown by the default 
output format, as wall as by the -j or - - jobid options to uucp(1) or uu(1). A job may only 
be rejuvenated by the user who created the job, or by the UUCP administrator or the 
superuser. The -r or - -rejuvenate options may be used multiple times on the command 
line to rejuvenate several jobs. 
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-Q) - 


=py = 


-i, - 


-list 


--status 
-ps 
-prompt 


--kill-all 


R, --rejuvenate-all 


--mail 


--notify 


- -comment 


--no-list 


-x type, --debug type 


-I file, --config file 
-v, --version 
--help 

EXAMPLES 


uustat -all 


uustat -executions 


Display the status of commands, executions, and conversations for all remote systems for 
which commands or executions are queued. The -s, --system, -S, --not-system, -o, - - 
older-than, -y, and - -younger- than options may be used to restrict the systems that are 
listed. Systens for which no commands or executions are queued will never be listed. 
Display the status of conversations for all renote systems. 

Display the status of all processes holding uucp locks on systems or ports. 

For each listed job, prompt whether to kill the job or not. If the first character of the input 
lineisy or y, the job will be killed. 

Automatically kill each listed job. This can be useful for automatic cleanup scripts, in 
conjunction with the - -mail and - -notify options. 

Automatically rejuvenate each listed job. This may not be used with - -kill-all. 

For each listed job, send mail to the UU CP administrator. If the job is killed (due to - - 
kill-all OF - -prompt with an affirmative response), the mail will indicate that. A comment 
specified by the - -comment option may beincluded. If the job is an execution, the initial 
portion of its standard input will be included in the mail message the number of lines to 
include may be set with the - -mail-1ines option (the default is 100). | f the standard input 
contains nul characters, it is assumed to bea binary file and is not included. 

For each listed job, send mail to the user who requested the job. The mail is identical to that 
sent by the -m or --mail options. 

Specify a comment to be included in mail sent with the -m, --mail, -N, OF --notify 
options. 

Do not actually list the job, but only take any actions indicated by the -i, --prompt, -k, -- 
kill-all, -M, --mail, -N, Of --notify options. 

Turn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing 
Only abnormal, config, spooldir, and execute are meaningful for uustat. 

M ultiple types may be given, separated by commas, and the - -debug option may appear 
multiple times. A number may also be given, which will turn on that many types from the 
foregoing list; for example, --debug 2isequivalent to --debug abnormal, chat. 

Sé configuration file to use This option may not be available, depending upon how uustat 
was compiled. 

Report version information and exit. 

Print ahap message and exit. 


Display status of all jobs. A sample output line is as follows: 

bugsA@27h bugs ian 04-01 13:50 Executing rmail ian@airs.com (sending 1283 
bytes) 

The format is 

jobid system user queue-date command (size) 

The jobid may be passed to the - -kill Or - -rejuvenate options. T he sizeindicates how 
much data isto be transferred to theremote system, and is absent for a file receive request. 
The --system, --not-system, --user, --not-user, --command, --not-command, - -older- 
than, and - -younger-than options may be used to control which jobs are listed. 

Display status of queued up execution requests. A sample output line is as follows: 

bugs bugs!ian 05-20 12:51 rmail ian 

The format is 

system requestor queue-date command 


The --system, --not-system, --user, --not-user, --command, --not-command, --older- 
than, and - -younger-than options may be used to control which requests are listed. 


uustat -list Display status for all systems with queued-up commands. A sample output line is as follows: 
bugs 4C (1 hour) OX (@ secs) 04-01 14:45 Dial failed 
This indicates the system, the number of queued commands, the age of the oldest queued 
command, the number of queued local executions, the age of the oldest queued execution, 
the date of the last conversation, and the status of that conversation. 

uustat -status Display conversation status for all remote systems. A sample output line is as follows: 
bugs 04-01 15:51 Conversation complete 
This indicates the system, the date of the last conversation, and thestatus of that conversa- 
tion. If the last conversation failed, uustat will indicate how many attempts have ben 


made to call the system. If the retry period is currently preventing calls to that system, 
uustat also displays the time when the next call will be permitted. 


uustat -ps Display the status of all processes holding uucp locks. The output format is system- 
dependent, as uustat simply invokes ps(1) on each process holding alock. A sample output 
lineis as follows: 


uustat -command rmail -older-than 168 -kill-all -no-list -mail -notify - 
comment "Queued for over 1 week" 


This will kill all rmai2 commands that have ben queued up waiting for ddivery for over 
one week (168 hours). For each such command, mail will be sent both to the UU CP 
administrator and to the user who requested the rmail execution. T he mail message sent 
will include the string given by the - -comment option. The - -no-1ist option prevents any 
of the jobs from being listed on the terminal, so any output from the program will be error 
messages. 


FILES 


The filenames may be changed at compilation time or by the configuration file, so these are only approximations. 


/usr/lib/uucp/config Configuration file 
/usr/spool/uucpuucp spool directory 


SEE ALSO 


ps(1), rmail(1), uucp(1), uux(1), uucico(8), uuxqt(8) 


AUTHOR 


lan Lance T aylor (ian@airs.com) 
Taylor UUCP 1.05 


UUX 

uux— Remote command execution over uucp 
SYNOPSIS 

uux [ options ] command 
DESCRIPTION 


The uux command is used to execute a command on a remote system, or to execute a command on the local system using 
files from remote systems. Thecommand is not executed immediately; the request is queued until the uucico(8) daemon 
calls the system and executes it. The daemon is started automatically unless oneof the -r or - -nouucico options is given. 
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The actual command execution is done by the uuxqt(8) daemon. 


File arguments can be gathered from remote systems to the execution systen, as can standard input. Standard output may be 
directed to afile on aremote system. 


The command name may be preceded by a system name followed by an exclamation point if it is to be executed on a remote 
system. An empty system nameis taken as the local system. 


Each argument that contains an exclamation point is treated as naming afile The system that the file is on is before the 
exclamation point, and the pathname on that system followsit. An empty system nameis taken as the local system; this must 
be used to transfer a file to a command being executed on a remote system. If the path isnot absolute it will be appended to 
the current working directory on the local system; the result may not be meaningful on the renote system. A pathname may 
begin with ~/, in which case it is relative to the uucp public directory (usually /usr/spool/uucppublic) on the appropriate 
system. A pathname may begin with ~name/, in which case it is relative to the home directory of the named user on the 
appropriate system. 

Standard input and output may be redirected as usual; the pathnames used may contain exclamation points to indicate that 
they are on remote systems. N ote that the redirection characters must be quoted so that they are passed to uux rather than 
interpreted by the shdl. Append redirection (>>) does not work. 


All specified files are gathered together into a single directory before execution of the command begins. T his means that each 
file must have a distinct base name. For example, 


uux 'sysi!diff sys2!~user1/foo sys3!~user2/foo >!foo.diff' 
will fail because both files will be copied to sys1 and stored under the name foo. 


Arguments may be quoted by parentheses to avoid interpretation of exclamation points. This is useful when executing the 
uucp Command on aremote system. 


OPTIONS 
The following options may be given to uux. 
-p, --stdin Read standard input and useit as the standard input for the command to be executed. 
-C, - -nocopy Do not copy local files to the spool directory. T hisis the default. If they are ranoved before 


being processed by the uucico(8) daenon, the copy will fail. T he files must be readable by 
the uucico(8) daemon, as wall as by the invoker of uux. 

-C, --copy Copy local files to the spool directory. 

-1, --link Link local files into the spool directory. If afile can not be linked because it is on a different 
device it will be copied unless one of the -c or - -nocopy options also appears (in other 
words, use of - -1ink switches the default from - -nocopy to - -copy). If the files are changed 
before being processed by the uucico(8) daemon, the changed versions will be used. The 
files must be readable by the uucico(8) daemon, as well as by the invoker of uux. 


-g grade, --grade grade Set the grade of the file transfer command. J obs of a higher grade are executed first. G rades 
run@... 9A... Za... zfromhigh to low. 
-n, --notification=no Do not send mail about the status of the job, even if it fails. 


-Z, --notification=er ror Send mail about the status of the job if an error occurs. For many uuxqt daemons, 
including the T aylor uucp uuxqt, this is the default action; for those, - - 
notification=error will haveno effect. However, some uuxqt daanons will send mail if 
the job succeeds unless the - -notification=error option isused, and some other uuxqt 
daemons will not send mail if the job fails unless the - -notification=error option is used. 

-P, --nouucico Do not start the uucico(8) daemon immediately; merdy queue up the execution request for 
later processing. 


-j, --jobid 


-a address, 
--requestor address 


-x type, --debug type 


-I file, --config file 


-v, --version 
--help 


EXAMPLES 


UUX 


Print jobids on standard output. A jobid will be generated for each file copy operation 
required to perform the operation. T hese file copies may be canceled by passing the jobia 
to the - -ki11 switch of uustat(1), which will make the execution impossible to complete. 


Report job status to the specified email address. 


Turn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 
Only abnormal, config, spooldir, and execute are meaningful for uux. Multiple types 
may be given, separated by commas, and the - - debug option may appear multiple times. A 
number may also be given, which will turn on that many types from the foregoing list; for 
example, --debug 2iS equivalent to --debug abnormal, chat. 

Sé& configuration file to use This option may not be available, depending upon how uux 
was compiled. 

Report version information and exit. 

Print ahap message and exit. 


uux -z - sys1!rmail useri— Execute the command rmail user1 on the system syst, giving it as standard input 
whatever is given to uux as standard input. If a failure occurs, send a message using mail(1). 


uux ‘diff -c sys1!"user1/file1 sys2!“user2/file2 >!file.diff'— Fetch thetwo named files from system sys1 and 
system sys2 and execute diff, putting the result in file. diff in the current directory. T he current directory must be 
writable by the uuxqt(8) daemon for this to work. 


uux 'sysi!uucp “user1/file1 (sys2!~“user2/file2) '— Execute uucp on the system sys1 copying file1 (on systen 
sys1) to sys2. This illustrates the use of parentheses for quoting. 


RESTRICTIONS 


The remote system may not permit you to execute certain commands. M any remote systems only permit the execution of 


rmail and rnews. 


Some of the options are dependent on the capabilities of the uuxqt(8) daenon on the renote system. 


FILES 


The filenames may be changed at compilation time or by the configuration file, so these are only approximations. 


/usr/lib/uucp/config 
/usr/spool/uucp uucp 
/usr/spool/uucp/Log 
/usr/spool/uucppublic 


SEE ALSO 


Configuration file 

spool directory 

uucp log file 

D efault uucp public directory 


mail(1), uustat(1), uucp(1), uucico(8), uuxqt(8) 


BUGS 


Files can not be referenced across multiple systems. 


T00 many jobids are output by - - jobid, and thereis no good way to cancd a local execution requiring remote files. 


AUTHOR 


lan Lance T aylor (ian@airs.com) 
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uuxqt 


uuxqt— uucp execution daanon 


SYNOPSIS 


uuxgt [ options ] 


DESCRIPTION 


The uuxqt daemon executes commands requested by uux(1) from either the local system or from remote systems. It is started 
automatically by the uucico(8) daemon (unless uucico(8) is given the -q or - -nouuxqt option). 


There is normally no need to run this command because it will be invoked by uucico(8). H owever, it can be used to provide 
greater control over the processing of the work queue. 


M ultiple invocations of uuxqt may be run at once, as controlled by themax-uuxqts configuration command. 


OPTIONS 


The following options may be given to uuxqt: 


-c command, --command command 


-S system, --system system 


-x type, --debug type 


-I file, --config 


-v, --version 
--help 


FILES 


Only execute requests for the specified command. For example, 

uuxqt -command rmail 

Only execute requests originating from the specified system. 

Turn on particular debugging types. The following types are recognized: abnormal, 
chat, handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, 
outgoing. Only abnormal, config, spooldir and execute are meaningful for 
uuxqt. M ultiple types may be given, separated by commas, and the - -debug option 
may appear multiple times. A number may also be given, which will turn on that 
many types from the foregoing list; for example, --debug 2 is equivalent to - -debug 
abnormal, chat. 

The debugging output is sent to the debugging file usually /usr/spoo1/uucp/ 
Debug, /usr/spool/uucp/DEBUG, OF /usr/spool/uucp/ .Admin/audit.local. 

Sé& configuration file to use This option may not be available, depending upon how 
uuxqt was compiled. 

Report version information and exit. 

Print ahap message and exit. 


The filenames may be changed at compilation time or by the configuration file, so these are only approximations. 


/usr/1lib/uucp/config Configuration file 


/usr/spool/uucp uucp spool directory 


/usr/spool/uucp/Log uucp log file 


/usr/spool/uucppublic — Default uucp public directory 


/usr/spool/uucp/Debug Debugging file 


SEE ALSO 


uucp(1), uux(1), uucico(8) 


AUTHOR 


lan Lance Taylor (ian@airs.com) 


Taylor UUCP 1.05 
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W 


w— Present who users are and what they are doing 


SYNOPSIS 


w [-hin] [-user] 


DESCRIPTION 


Thew utility prints a summary of the current activity on the system, including what each user is doing. The first line displays 
the current time of day, how long the system has been running, the number of users logged into the system, and the load 
averages. The load average numbers give the number of jobs in the run queue averaged over 1, 5, and 15 minutes. 


The fields output are the user’s login name, the name of the terminal the user is on, the host from which the user is logged 
in, the time the user logged on, the time since the user last typed anything, and the name and arguments of the current 
process. 


The options are as follows: 


-h Suppress the heading 

“i O utput is sorted by idle time 

-n Show network addresses as numbers 

-W Interpret addresses and attempt to display than symbolically 


If a username is specified, the output is restricted to that user. 


FILES 


/var/run/utmp List of users on the system 


SEE ALSO 


who(1), finger(1), ps(1), uptime(1), 


BUGS 


The notion of the current process ismuddy. The current algorithm is “the highest numbered process on the terminal that is 
not ignoring interrupts, or, if there is none, the highest numbered process on theterminal.” T his fails, for example, in critical 
sections of programs like the shell and editor, or when faulty programs running in the background fork and fail to ignore 
interrupts. (In cases where no process can be found, w prints a period.) 


TheCPU timeis only an estimate; in particular, if someone leaves a background process running after logging out, the 
person currently on that terminal is charged with the time 


Background processes are not shown, even though they account for much of the load on the system. 


Sometimes processes, typically those in the background, are printed with null or garbaged arguments. In these cases, the 
name of the command is printed in parentheses. 


The w utility does not know about the new conventions for detection of background jobs. It will sometimes find a back- 
ground job instead of the right one. 


COMPATIBILITY 


The -f, -1, -s, and -w flags are no longer supported. 
HISTORY 
Thew command appeared in BSD 3.0. 
BSD 4, 6 June1993 
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wall 


wal1— W rite a message to users 


SYNOPSIS 


wall [file] 


DESCRIPTION 
wall displays the contents of file or, by default, its standard input, on the terminals of all currently logged in users. 


Only the superuser can write on the terminals of users who have chosen to deny messages or are using a program that 
automatically denies messages. 


SEE ALSO 


mesg(1), talk(1), write(1), snutdown(8) 
HISTORY 
A wall command appeared in AT &T v7. 
Linux 0.99, 8 March 1993 


we 

we— Print the number of bytes, words, and lines in files 
SYNOPSIS 

we [-clw] [--bytes] [--chars] [--lines] [--words] [--help] [--version] [file...] 
DESCRIPTION 


This manual page documents the GN U version of we. we counts the number of bytes, whitespace separated words, and 
newlines in each given file, or the standard input if none are given or when afilenamed - is given. It prints one line of 
counts for each file, and if the file was given as an argument, it prints the filename following the counts. If more than one 
filename is given, we prints a final line containing the cumulative counts, with the filamame total. The counts are printed in 
the order lines, words, bytes. 


By default, we prints all three counts. O ptions can specify that only certain counts be printed. O ptions do not undo others 
previously given, SO wc --bytes --words prints both the byte counts and the word counts. 


OPTIONS 
-c, --bytes, --chars _ Print only the byte counts. 
-w, - -words Print only the word counts. 
-1, --lines Print only the newline counts. 
--help Print a usage message and exit with a non-zero status. 
--version Print version information on standard output, then exit. 
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whereis 


whereis— Locate the binary, source, and manual page files for a command 


SYNOPSIS 


whereis [ -bmsu ][-BMS directory... -f ] filename ... 


DESCRIPTION 


whereis locates source/binary and manuals sections for specified files. The supplied names are first stripped of leading 
pathname components and any (single) trailing extension of the form . ext, for example, .c. Prefixes of s. resulting from use 
of source code control are also dealt with. wnereis then attempts to locate the desired program in alist of standard Linux 
places: 


/bin 

/usr/bin 

/etc 

/usr/etc 

/sbin 

/usr/sbin 

/usr/games 
/usr/games/bin 
/usr/emacs/etc 
/usr/lib/emacs/19.22/etc 
/usr/lib/emacs/19.23/etc 
/usr/lib/emacs/19.24/etc 
/usr/lib/emacs/19.25/etc 
/usr/lib/emacs/19.26/etc 
/usr/lib/emacs/19.27/etc 
/usr/lib/emacs/19.28/etc 
/usr/lib/emacs/19.29/etc 
/usr/lib/emacs/19.30/etc 
/usr/TeX/bin 
/usr/tex/bin 
/usr/interviews/bin/LINUX 
/usr/bin/X11 
/usr/X11/bin 
/usr/X11R5/bin 
/usr/X11R6/bin 
/usr/X386/bin 
/usr/local/bin 
/usr/local/etc 
/usr/local/sbin 
/usr/local/games 
/usr/local/games/bin 
/usr/local/emacs/etc 
/usr/local/TeX/bin 
/usr/local/tex/bin 
/usr/local/bin/X11 
/usr/contrib 

/usr/hosts 

/usr/include 
/usr/gtt+-include 
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OPTIONS 
-b Search only for binaries. 
-m Search only for manual sections. 
“8 Search only for sources. 
-u Search for unusual entries. A fileis said to be unusual if it does not have one entry of each requested type. T hus 
whereisnn-mnn-unn* asks for those filesin the current directory which haveno documentation. 
-B Change or otherwise limit the places where whereis searches for binaries. 
-M Change or otherwise limit the places where whereis searches for manual sections. 
-S Change or otherwise limit the places where whereis searches for sources. 
-f Terminate the last directory list and signals the start of filenames; mus be used when any of the -B, -m, or -s 
options are used. 
EXAMPLE 


Find all filesin /usr/bin that are not documented in /usr/man/mani with sourcein /usr/src: 


example%’ cd /usr/bin 
example% whereis -u -M /usr/man/mant -S /usr/src -f * 


FILES 


/{bin,sbin, etc} 
/usr/{lib,bin,old,new, local, games, include,etc,src,man,sbin, 
X386, TeX, gt+-include} 

/usr/local/{X386,TeX,X11, include, lib,man,etc,bin, games, emacs} 


SEE ALSO 
chdir(2V) 


BUGS 


Since whereis uses chdir(2V) to run faster, pathnames given with the -m, -s, or -B must be full; that is, they must begin 
with a/. 


8 May1994 


write 


write— Send a message to another user 


SYNOPSIS 


write user [ttyname ] 


DESCRIPTION 
write allows you to communicate with other users by copying lines from your terminal to thers. 
When you run thewrite command, the user you are writing to gets a message of the form: 


Message from yourname@yourhost on yourtty at hh:mm ... 


Any further lines you enter will be copied to the specified user’s terminal. If the other user wants to reply, he or she must run 
write aswell, 


When you are done, type an end-of-file or interrupt character. The other user will see the message Eor, indicating that the 
conversation is over. 
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You can prevent people (other than the superuser) from writing to you with themesg(1) command. Some commands, for 
example, nrof#(1) and pr(1), may disallow writing automatically, so that your output isn’t overwritten. 


If the user you want to write to is logged in on more than one terminal, you can specify which terminal to write to by 
specifying the terminal name as the second oper and to the write command. Alternatively, you can let write sdect one of 
the terminals— it will pick the one with the shortest idle time T hus, if the user islogged in at work and also dialed up from 
home, the message will go to the right place. 


Thetraditional protocol for writing to someoneis that the string -o, either at the end of aline or on aline by itself, means 
that it’s the othe person’s turn to talk. The string oo means that the person beiieves the conversation to be over. 


SEE ALSO 


mesg(1), talk(1), who(1) 


HISTORY 
A write command appeared in Version 6 AT&T UNIX. 


12 March 1995 


x11 perf 


x11perf— X11 server performance test program 


SYNTAX 


xliperf [ -option ... ] 


DESCRIPTION 


The x11perf program runs one or more performance tests and reports how fast an x server can execute the tests. 


M any graphics benchmarks assume that the graphics deviceis used to display the output of a single fancy graphics applica- 
tion, and that the user gets his work done on someother device like a terminal. Such benchmarks usually measure drawing 
speed for lines, polygons, text, and so on. 


Because workstations are not used as standalone graphics engines, but as super-terminals, x11perf measures window 
management performance as well as traditional graphics performance x11perf includes benchmarks for thetimeit takes to 
create and map windows (as when you start up an application); to map a preexisting set of windows onto thescreen (as when 
you deiconify an application or pop up a menu); and to rearrange windows (as when you slosh windows to and fro trying to 
find the one you want). 


x11perf also measures graphics performance for operations not normally used in standalone graphics displays, but are 
nonetheless used frequently by x applications. Such operations include copyPlane (used to map bitmaps into pixds), 
scrolling (used in text windows), and various stipples and tiles (used for CAD and color halftoning, respectively). 


x11perf should be used to analyze particular strengths and weaknesses of servers, and is most useful to a server writer who 
wants to analyze and improve a serve. x11perf ismeant to comprehensivey exercise just about every X11 operation you can 
perform; it does not purport to be a representative sample of the operations that X11 applications actually use. Although it 
can be used as a benchmark, it was written and is intended as a performance testing tool. 


Assuch, x11perf does not whittle down measurements to a single HexStones OF Mexops number. W econsider such numbers 
to be uninformative at best and misleading at worst. Some servers that are very fast for certain applications can be very slow 
for others. No single number or small set of numbers is sufficient to characterize how an x implementation will perform on 
all applications. H owever, by knowledge of your favorite application, you may be able to use the numbers x11perf reports to 
predict its performance on a given x implementation. 
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That said, you might also want to look at x11perfcomp(1), a program to compare the outputs of different x11perf runs. You 
provide alist of files containing results from x11perf, and it lays then out in a nice tabular format. 


For repeatable results, x11perf should be run using alocal connection on a freshly started server. The default configuration 
runs each test five times in order to see if each trial takes approximatdy the same amount of time. Strange glitches should be 
examined; if nonrepeatable, you might chalk them up to daemons and network traffic. Each trial isrun for five seconds, in 
order to reduce random time differences. The number of objects processed per second is displayed to three significant digits, 
but you'll be lucky on most UNIX systems if the numbers are actually consistent to two digits. x11perf moves the cursor out 
of the test window; you should be careful not to bump the mouse and moveit back into the window. (A prize to people who 
correctly explain why!) 


Before running atest, x11perf determines what the round trip time to the server is, and factors this out of the final timing 
reported. It ensures that the server has actually performed the work requested by fetching a pixa back from the test window, 
which means that servers talking to graphics accderators can’t claim that they are done while in the meantime the accdera- 
tor is painting madly. 


By default, x11perf automatically calibrates the number of repetitions of each test, so that each should take approximatdy 
the same length of time to run across servers of widely differing speeds. H owever, because each test must be run to comple 
tion at least once, some slow servers may take a very long time, particularly on the window moving and resizing tests, and on 
the arc drawing tests. 


All timing reports are for the smallest object involved. For example, the line tests use a PolyLine request to paint several lines 
at once, but report how many lines per second the server can paint, not how many PolyLine requests per second. T ext tests 
paint a line of characters, but report on the number of characters per second. Some window tests map, unmap, or move a 
single parent window, but report on how many children windows per second the server can map, unmap, or move 


Thecurrent program is mostly the responsibility of Joel M cC ormack. It is based upon the x11perf developed by Phil 
Karlton, Susan Angebranndt, Chris Kent, M ary Walker, and Todd N avman, who wanted to assess performance differences 
between various servers. Several tests were added in order to write and tunethe PM AX (DECStation 3100) servers. Fora 
general release to the world, x11perf was rewritten to ease making comparisons between widely varying machines, to cover 
most important (and unimportant) x functionality, and to exercise graphics operations in as many different orientations and 
alignments as possible. 


OPTIONS 


x11perf is soldy x1ib based, and accepts the following options: 


-display host: dpy 
-sync 


-pack 


-repeat <n> 

-time <s> 

-all 

-range 
<testl>[,<test2>] 


-labels 


-fg color-or-pi xel 


-bg color-or-pixel 


-clips default 


Specifies which display to use 

Runs the tests in synchronous mode. N ormally only useful for debugging x11perf. 

Runs rectangle tests so that they pack rectangles right next to each other. This makes it easy 
to debug server code for stipples and tiles; if the pattern looks ugly, you've got alignment 
problems. 

Repeats each test n times (by default each test is run fivetimes). 

Specifies how long in seconds each test should be run (default 5 seconds). 

Runs all tests. This may take a while 


Runs all the tests starting from the specified namet est 1 until thenamet est 2, tests. The 
testnames should be one of the options starting from -dot. For example, -range 1ine100 
will perform the tests from the 100 pixd line test, and go on till the last test; - range 
line100,dline1@ will do the tests from 1ine100 to dline1o. 


Generates just the descriptive labels for each test specified. See x11perfcomp for more 
details. 


Specifies the foreground color or pixel value to use. 
Specifies the background color or pixe value to use. 
D efault number of clip windows. 


-ddbg color-or-pi xel 


-rop <ropO rop1 ...> 


-pm <pmd pml ...> 


-depth <dept h> 


-vclass <vclass> 


-reps <n> 





-subs <s0 sl ...> 


-v1.2 
-Vv1.3 


-SU 


-bs 
<backing_store_hint> 
-dot 

-rect1 
-rect10 
-rect100 
-rect500 
-srecti 
-srect10 
-srect100 
-srect500 
-osrect1 
-osrect10 
-osrect100 
-osrect500 
-tilerect1 
-tilerect10 
-tilerect100 
-tilerect500 
-oddsrect1 
-oddsrect10 
-oddsrect100 
-oddsrect500 
-oddosrect1 
-oddosrect10 
-oddosrect100 
-oddosrect500 
-oddtilerect1 
-oddtilerect10 
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Specifies the color or pixd value to use for drawing the odd segments of a DoubleDashed 
lineor arc. This will default to the bg color. 


Use specified raster ops (default is xcopy). This option only affects graphics benchmarks in 
which the graphics function is actually used. 


Use specified planemasks (default is ~@). This option only affects graphics benchmarks in 
which the planemask is actually used. 


Use avisual with <depth> planes per pixel. (D efault is the default visual.) 


Usea visual with of class <vcl ass>. <vclass>Can beStaticGray, GrayScale, 
StaticColor, PseudoColor, TrueColor, OF DirectColor. (Default isthedefault visual). 


Specify the repetition count. (D efault isnumber that takes approximately five seconds.) 


Specify the number of sub windows to usein the W indow tests. D efault is 4, 16, 25, 50, 75, 
100, and 200. 


Perform only x11perf version 1.2 tests using version 1.2 semantics. 
Perform only x11perf version 1.3 tests using version 1.3 semantics. 


Se the save_under window attribute to True on all windows created by x11perf. Default is 
False 


Set the backing_store window attribute to the given value on all windows created by 
x11perf. <backing_store_hint> Can be WhenMapped OF Always. D efault isNotUseful. 


Dot. 

1x1 solid-filled rectangle. 

10x10 solid-filled rectangle. 

100x100 solid-filled rectangle. 

500x500 solid-filled rectangle. 

1x1 transparent stippled rectangle, 8x8 stipple pattern. 
10x10 transparent stippled rectangle, 8x8 stipple pattern. 
100x100 transparent stippled rectangle, 8x8 stipple pattern. 
500x500 transparent stippled rectangle, 8x8 stipple pattern. 
1x1 opaque stippled rectangle, 8x8 stipple pattern. 

10x10 opaque stippled rectangle 8x8 stipple pattern. 
100x100 opaque stippled rectangle, 8x8 stipple pattern. 
500x500 opaque stippled rectangle, 8x8 stipple pattern. 
1x1 tiled rectangle 4x4 tile pattern. 

10x10 tiled rectangle, 4x4 tile pattern. 

100x100 tiled rectangle, 4x4 tile pattern. 

500x500 tiled rectangle 4x4 tile pattern. 

1x1 transparent stippled rectangle, 17x15 stipple pattern. 
10x10 transparent stippled rectangle, 17x15 stipple pattern. 
100x100 transparent stippled rectangle, 17x15 stipple pattern. 
500x500 transparent stippled rectangle, 17x15 stipple pattern. 
1x1 opaque stippled rectangle, 17x15 stipple pattern. 
10x10 opaque stippled rectangle 17x15 stipple pattern. 
100x100 opaque stippled rectangle, 17x15 stipple pattern. 
500x500 opaque stippled rectangle, 17x15 stipple pattern. 
1x1 tiled rectangle 17x15 tile pattern. 

10x10 tiled rectangle, 17x15 tile pattern. 
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-oddtilerect100 
-oddtilerect500 
-bigsrect1 
-bigsrect10 
-bigsrect100 
-bigsrect500 
-bigosrect1 
-bigosrect10 
-bigosrect100 
-bigosrect500 
-bigtilerect1 
-bigtilerect10 
-bigtilerect100 
-bigtilerect500 
-eschertilerect1 
-eschertilerect10 
-eschertilerect100 
-eschertilerect500 
-segi 

-segid 

-seg100 

-seg500 
-seg100c1 
-seg100c2 
-$eg100c3 
-dseg10 
-dseg100 
-ddseg100 
-hseg10 
-hseg100 
-hseg500 
-vseg10 
-vseg100 
-vseg500 
-whseg10 
-whseg100 
-whseg500 
-wvseg10 
-wvseg100 
-wvseg500 
-line1 

-line10 
-line100 
-line500 


100x100 tiled rectangle, 17x15 tile pattern. 
500x500 tiled rectangle 17x15 tile pattern. 

1x1 stippled rectangle, 161x145 stipple pattern. 
10x10 stippled rectangle, 161x145 stipple pattern. 
100x100 stippled rectangle, 161x145 stipple pattern. 
500x500 stippled rectangle, 161x145 stipple pattern. 
1x1 opaque stippled rectangle, 161x145 stipple pattern. 
10x10 opaque stippled rectangle 161x145 stipple pattern. 
100x100 opaque stippled rectangle, 161x145 stipple pattern. 
500x500 opaque stippled rectangle, 161x145 stipple pattern. 
1x1 tiled rectangle 161x145 tile pattern. 

10x10 tiled rectangle, 161x145 tile pattern. 
100x100 tiled rectangle 161x145 tile pattern. 
500x500 tiled rectangle 161x145 tile pattern. 

1x1 tiled rectangle, 215x208 tile pattern. 

10x10 tiled rectangle, 215x208 tile pattern. 
100x100 tiled rectangle 215x208 tile pattern. 
500x500 tiled rectangle 215x208 tile pattern. 
1-pixd thin line segment. 

10-pixd thin line segment. 

100-pixel thin line segment. 

500-pixel thin line segment. 

100-pixel thin line segment (1 obscuring rectangle). 
100-pixel thin line segment (2 obscuring rectangles). 
100-pixel thin line segment (3 obscuring rectangles). 
10-pixe thin dashed segment (3 on, 2 off). 

100-pixel thin dashed segment (3 on, 2 off). 
100-pixel thin double dashed segment (3 fg, 2 bg). 
10-pixd thin horizontal line segment. 

100-pixel thin horizontal line segment. 

500-pixel thin horizontal line segment. 

10-pixd thin vertical line segment. 

100-pixel thin vertical line segment. 

500-pixel thin vertical line segment. 

10-pixd wide horizontal line segment. 

100-pixel wide horizontal line segment. 

500-pixel wide horizontal line segment. 

10-pixd wide vettical line segment. 

100-pixel wide vertical line segment. 

500-pixel wide vertical line segment. 

1-pixd thin (width 0) line 

10-pixd thin line. 

100-pixel thin line 

500-pixel thin line 
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-dline10 10-pixd thin dashed line (3 on, 2 off). 

-dline100 100-pixel thin dashed line (3 on, 2 off). 

-ddline100 100-pixel thin double dashed line (3 fg, 2 bg). 

-wline10 10-pixd line, line width 1. 

-wline100 100-pixel line, line width 10. 

-wline500 500-pixel line, line width 50. 

-wdline100 100-pixel dashed line, linewidth 10 (30 on, 20 off). 

-wddline100 100-pixel double dashed line, linewidth 10 (30 fg, 20 bg). 

-orect10 10x10 thin rectangle outline. 

-orect100 100-pixel thin vertical line segment. 

-orect500 500-pixel thin vertical line segment. 

-worect10 10x10 wide rectangle outline 

-worect100 100-pixel wide vertical line segment. 

-worect500 500-pixel wide vertical line segment. 

-circle1 1-pixd diameter thin (line-width @) circle. 

-circle10 10-pixd diameter thin circle. 

-circle100 100-pixel diameter thin circle. 

-circle500 500-pixel diameter thin circle. 

-dcircle100 100-pixel diameter thin dashed circle (3 on, 2 off). 

-ddcircle100 100-pixel diameter thin double dashed circle (3 fg, 2 bg). 

-weircle10 10-pixd diameter circle line width 1. 

-weircle100 100-pixel diameter circle, line width 10. 

-weircle50o 500-pixel diameter circle, line width 50. 

-wdeircle10o 100-pixel diameter dashed circle linewidth 10 (30 on, 20 off). 

-wddcircle100 100-pixel diameter double-dashed circle line width 10 (30 fg, 20 bg). 

-peircle10 10-pixe diameter thin partial circle, orientation and arc angle evenly distributed. 

-pcircle100 100-pixel diameter thin partial circle 

-wpcircle10 10-pixd diameter wide partial circle. 

-wpcircle100 100-pixel diameter wide partial circle. 

-fcirclet 1-pixd diameter filled circle 

- fcircle10 10-pixe diameter filled circle 

-fcircle100 100-pixel diameter filled circle 

-fcircle500 500-pixel diameter filled circle 

-fcepcircle10 10-pixd diameter partial-filled circle chord fill, orientation and arc angle evenly distributed. 

-fcepcircle100 100-pixel diameter partial-filled circle chord fill. 

-fspcircle10 10-pixd diameter partial-filled circle pie slice fill, orientation and arc angle evenly 
distributed. 

-fspcircle100 100-pixel diameter partial-filled circle, pie slice fill. 

-ellipse10 10-pixd diameter thin (line width 0) ellipse, major and minor axis sizes evenly distributed. 

-ellipse100 100-pixel diameter thin dlipse. 

-ellipse500 500-pixel diameter thin dlipse. 

-dellipse100 100-pixel diameter thin dashed dlipse (3 on, 2 off). 

-ddellipse100 100-pixel diameter thin double dashed ellipse (3 fg, 2 bg). 








-wellipse10 10-pixd diameter ellipse, line width 1. 


-wellipse100 
-wellipse500 
-wdellipse100 
-wddellipse100 
-pellipse10 
-pellipse100 
-wpellipse10 
-wpellipse100 
-fellipse10 
-fellipse100 
-fellipse500 
-fcpellipse10 
-fcpellipse100 
-fspellipse10 
-fspellipse100 
-triangle1 
-triangle10 

- triangle100 
-trap1 

-trap10 
-trap100 
-trap300 





-strap1 
-strap10 
-strap100 
-strap300 
-ostrap1 
-ostrap10 
-ostrap100 
-ostrap300 
-tiletrap1 
-tiletrap10 
-tiletrap100 
-tiletrap300 
-oddstrap1 
-oddstrap10 
-oddstrap100 
-oddstrap300 
-oddostrap1 
-oddostrap10 
-oddostrap100 
-oddostrap300 
-oddtiletrap1 
-oddtiletrap10 
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100-pixel diameter ellipse, line width 10. 

500-pixel diameter ellipse, line width 50. 

100-pixel diameter dashed ellipse, line width 10 (30 on, 20 off). 
100-pixel diameter double-dashed ellipse, line width 10 (30 fg, 20 bg). 


10-pixd diameter thin partial dlipse. 

100-pixel diameter thin partial dlipse. 

10-pixd diameter wide partial ellipse. 

100-pixel diameter wide partial dlipse 

10-pixd diameter filled ellipse 

100-pixel diameter filled ellipse 

500-pixel diameter filled ellipse. 

10-pixd diameter partial-filled ellipse, chord fill. 
100-pixel diameter partial-filled ellipse, chord fill. 
10-pixd diameter partial-filled ellipse, pie slice fill. 
100-pixel diameter partial-filled ellipse, pie slice fill. 
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1-pixel/side triangle 

10-pixd/side triangle. 

100-pixd/side triangle. 

1x1 trapezoid. 

10x10 trapezoid. 

100x100 trapezoid. 

300x300 trapezoid. 

1x1 transparent stippled trapezoid, 8x8 stipple pattern. 
10x10 transparent stippled trapezoid, 8x8 stipple pattern. 
100x100 transparent stippled trapezoid, 8x8 stipple pattern. 
300x300 transparent stippled trapezoid, 8x8 stipple pattern. 
10x10 opaque stippled trapezoid, 8x8 stipple pattern. 
10x10 opaque stippled trapezoid, 8x8 stipple pattern. 
100x100 opaque stippled trapezoid, 8x8 stipple pattern. 
300x300 opaque stippled trapezoid, 8x8 stipple pattern. 
10x10 tiled trapezoid, 4x4 tile pattern. 

10x10 tiled trapezoid, 4x4 tile pattern. 

100x100 tiled trapezoid, 4x4 tile pattern. 

300x300 tiled trapezoid, 4x4 tile pattern. 

1x1 transparent stippled trapezoid, 17x15 stipple pattern. 
10x10 transparent stippled trapezoid, 17x15 stipple pattern. 
100x100 transparent stippled trapezoid, 17x15 stipple pattern. 
300x300 transparent stippled trapezoid, 17x15 stipple pattern. 
10x10 opaque stippled trapezoid, 17x15 stipple pattern. 
10x10 opaque stippled trapezoid, 17x15 stipple pattern. 
100x100 opaque stippled trapezoid, 17x15 stipple pattern. 
300x300 opaque stippled trapezoid, 17x15 stipple pat-tern. 
10x10 tiled trapezoid, 17x15 tile pattern. 

10x10 tiled trapezoid, 17x15 tile pattern. 








-oddtiletrap100 
-oddtiletrap300 
-bigstrap1 
-bigstrap10 
-bigstrap100 
-bigstrap300 
-bigostrap1 
-bigostrap10 
-bigostrap100 
-bigostrap300 
-bigtiletrap1 
-bigtiletrap10 
-bigtiletrap100 
-bigtiletrap300 
-eschertiletrap1 
-eschertiletrap10 
-eschertiletrap100 
-eschertiletrap300 
-complex10 
-complex100 
-64poly1@convex 

- 64poly1@@convex 
-64poly1@complex 
-64poly1@0complex 
-ftext 

-f8text 

-f9text 
-F14text16 

- tr10text 
-tr24text 
-polytext 
-polytext16 
-fitext 

-F8itext 

-Fgitext 
-F14itext16 
-F24itext16 
-triditext 





-tr24itext 
-scrol1l10 

-scrol1100 
-scro11500 


100x100 tiled trapezoid, 17x15 tile pattern. 

300x300 tiled trapezoid, 17x15 tile pattern. 

1x1 transparent stippled trapezoid, 161x145 stipple pattern. 
10x10 transparent stippled trapezoid, 161x145 stipple pattern. 


10x10 opaque stippled trapezoid, 161x145 stipple pattern. 
10x10 opaque stippled trapezoid, 161x145 stipple pattern. 
100x100 opaque stippled trapezoid, 161x145 stipple pattern. 
300x300 opaque stippled trapezoid, 161x145 stipple pattern. 
10x10 tiled trapezoid, 161x145 tile pattern. 

10x10 tiled trapezoid, 161x145 tile pattern. 

100x100 tiled trapezoid, 161x145 tile pattern. 

300x300 tiled trapezoid, 161x145 tile pattern. 

1x1 tiled trapezoid, 216x208 tile pattern. 

10x10 tiled trapezoid, 216x208 tile pattern. 

100x100 tiled trapezoid, 216x208 tile pattern. 

300x300 tiled trapezoid, 216x208 tile pattern. 
10-pixd/side complex polygon. 

100-pixd/side complex polygon. 

10x10 convex 64-gon. 

100x100 convex 64-gon. 

10x10 complex 64-gon. 

Fill 100x100 complex 64-gon. 

Character in 80-char line (6x13). 

Character in 70-char line (8x13). 

Character in 60-char line (9x15). 

2-byte character in 40-char line (k14). 

Character in 80-char line (Times-Roman 10). 

Character in 30-char line (Times-Roman 24), 

Character in 20/40/20 line (6x13, T imes-Roman 10, 6x13). 
2-byte character in 7/14/7 line(k14, k24). 

Character in 80-char image line (6x13). 

Character in 70-char image line (8x13). 

Character in 60-char image line (9x15). 

2-byte character in 40-char image line (k14). 

2-byte character in 23-char image line (k24). 

Character in 80-char image line (Times-Roman 10). 
Character in 30-char image line (Times-Roman 24). 

Scroll 10x10 pixels vertically. 

Scroll 100x100 pixds vertically. 

Scroll 500x500 pixds vertically. 
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100x100 transparent stippled trapezoid, 161x145 stipple pattern. 
300x300 transparent stippled trapezoid, 161x145 stipple pattern. 
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-copywinwin1d 
-copywinwin100 
- copywinwin500 
-copypixwin1d 
-copypixwin100 
-copypixwin500 
-copywinpix1d 
-copywinpix100 
-copywinpix500 
-copypixpix1d 
-copypixpix100 
-copypixpix500 
-copyplane10 
-copyplane100 
-copyplane500 
-putimage10 
-putimage100 
-putimage500 
-putimagexy10 
-putimagexy100 
-putimagexy500 
-shmput10 
-shmput100 

- shmput500 
-shmputxy10 
-shmputxy100 
-shmputxy500 
-getimage10 
-getimage100 
-getimage500 
-getimagexy10 
-getimagexy100 
-getimagexy500 
-noop 

-atom 

-pointer 

-prop 

-ge 

-create 
-ucreate 

-map 

-unmap 
-destroy 

- popup 
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Copy 10x10 square from window to window 

Copy 100x100 square from window to window. 

Copy 500x500 square from window to window. 

Copy 10x10 square from pixmap to window. 

Copy 100x100 square from pixmap to window 

Copy 500x500 square from pixmap to window. 

Copy 10x10 square from window to pixmap. 

Copy 100x100 square from window to pixmap. 

Copy 500x500 square from window to pixmap. 

Copy 10x10 square from pixmap to pixmap 

Copy 100x100 square from pixmap to pixmap. 

Copy 500x500 square from pixmap to pixmap. 

Copy 10x10 1-bit deep plane. 

Copy 100x100 1-bit deep plane. 

Copy 500x500 1-bit deep plane. 

Putlmage 10x10 square 

Putl mage 100x100 square 

Putl mage 500x500 square 

Putlmage XY format 10x10 square 
Putlmage XY format 100x100 square. 

Putlmage XY format 500x500 square. 

Putlmage 10x10 square, MIT -shared memory extension. 
Putlmage 100x100 square, M IT -shared memory extension. 
Putl mage 500x500 square, M IT -shared memory extension. 
Putlmage XY format 10x10 square, MIT -shared memory extension. 
Putlmage XY format 100x100 square, M IT -shared memory extension. 
Putlmage XY format 500x500 square, M IT -shared memory extension. 
Getl mage 10x10 square. 

Getl mage 100x100 square. 

Getl mage 500x500 square. 
Getlmage XY format 10x10 square 

Getlmage XY format 100x100 square. 

Getlmage XY format 500x500 square. 

X protocol Nodperation 

GetAtomName. 

QueryPointer. 

GetProperty. 

Change graphics context. 

Create child window and map using MapSubwindows. 
Create unmapped window. 

M ap child window via Mapwindow on parent. 

Unmap child window via Unmapwindow on parent. 

Destroy child window via DestroyWindow parent. 

H ide/expose window via M ap/U nmap pop-up window. 
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-move M ove window. 
-umove M oved unmapped window. 
-movetree M ove window via MoveWindow on parent. 
-resize Resize window. 
-uresize Resize unmapped window. 
-circulate Circulate lowest window to top. 
-ucirculate Circulate unmapped window to top. 
X DEFAULTS 
There are no x defaults used by this program. 
SEE ALSO 
x(1), xbench(1), x11perfcomp(1) 
AUTHORS 
Joel M cCormack 
Phil Karlton 
Susan Angebranndt 
ChrisK ent 
Keith Packard 
Graeme Gill 


X Verdon 11 Reease 6 


x11 perf comp 


x11perfcomp— X11 server performance comparison program 


SYNTAX 


x11perfcomp [-rj -ro ] [ -1 label file ] files 


DESCRIPTION 


The x11perfcomp program merges the output of several x11perf(1) runs into anicetabular format. It takes the results in 
each file, fills in any missing test results if necessary, and for each test shows the objects/second rate of each server. If invoked 
with the -r or -ro options, it shows the rdative performance of each server to the first server. 

Normally, x11perfcomp uses the first file specified to determine which specific tests it should report on. Some (non-D EC:) 
servers may fail to perform all tests. In this case, x11perfcomp automatically substitutes in a rate of 0. @ objects/second. Since 
the first file determines which tests to report on, thisfile must contain a superset of the tests reported in the other files, else 
x11perfcomp will fail. 


You can providean explicit list of tests to report on by using the -1 switch to specify a file of labels. You can create a label file 
by using the -1abe1 option in x11perf. 

OPTIONS 
x11perfcomp accepts the following options: 


-r Specifies that the output should also include relative server performance. 
-ro Specifies that the output should include only relative server performance 
-l_label_ file Specifiesalabd file to use 
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X DEFAULTS 
There are no x defaults used by this program. 


SEE ALSO 
x(1), x11pert(1) 


AUTHORS 
M ark M oraes wrote the original scripts to compare servers. J oel McCormack just munged them together a bit. 
X Verson 11 Release 6 


xargs 


xargs— Build and execute command lines from standard input 


SYNOPSIS 
xargs [-Oprtx] [-e[eof-str]] [-if[replace-str]] [-1l[max-lines]] [-n max-args] 
[-s max-chars] [-P max-procs] [--null] [--eof[=eof-str]] [--replace[=replace-str] 
[--max-lines[=max-lines]] [--interactive] [--max-chars=max-chars] [--verbose] 
[--exit] [--max-procs=max-procs] [--max-args=max-args] [--no-run-if-empty] 
[--version] [--help] [command [initial-arguments]] 

DESCRIPTION 


This manual page documents the GN U version of xargs. xargs reads arguments from the standard input, delimited by 
blanks (which can be protected with double or single quotes or a backslash) or newlines, and executes the commana (default is 
/bin/echo) oneor more times with any initial-arguments followed by arguments read from standard input. Blank lines 
on the standard input are ignored. 
xargs exits with the following status: 

@ if it succeeds 

123 if any invocation of the command exited with status 1 - 125 

124 if the command exited with status 255 

125 if the command is killed by asignal 

126 if the command cannot berun 

127 if the command is not found 

1 if some other error occurred. 


OPTIONS 

--null, -@ Input filenames are taminated by a null character instead of by whitespace, and the quotes 
and backslash are not special (every character is taken literally). D isables the end-of-file 
string, which is treated like any other argument. U seful when arguments might contain 
whitespace, quote marks, or backslashes. TheGN U find -printe option producesinput 
suitable for this mode 

--eof[=eof-str], Sé& the end-of-file string to eof-str. If the end-of-file string occurs as a line of input, the 

-e[eof-str] rest of the input isignored. If eof-str is omitted, thereis no end of filestring. If this 
option is not given, the end-of-file string defaults to an underscore. 

--help Print asummary of the options to xargs and exit. 

--replace[=replace-str], Replace occurrences of rep| ace- str in theinitial arguments with names read from 

-i[replace-str] standard input. Also, unquoted blanks do not terminate arguments. If replace-str 


is omitted, it defaults to 4} (like for find -exec). |mplies -x and -1 1. 
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- -max-lines[=max- lines], Use at most max-|ines nonblank input lines per command line max-| ines defaults to 1 

-l[max-lines] if omitted. T railing blanks cause an input line to be logically continued on the nett input 
line Implies -x. 

--max -args=max- args, Use at most max- args arguments per command line Fewer than max- args arguments will 

-n max- args be used if the size (see the -s option) is exceeded, unless the - x option is given, in which 
case xargs will exit. 

--interactive, -p Prompt the user about whether to run each command line and read a line from the 
terminal. O nly run the command line if the response starts with y or y. Implies -t. 

--no-run-if-empty, -r If the standard input does not contain any nonblanks, do not run the command. N ormdly, 
the command isrun once even if there is no input. 

- -max-chars=max- chars, Use at most max- chars characters pe’ command line including the command and initial 

-S max- chars arguments and the terminating nu11s at the ends of the argument strings. T he default is 
as large as possible, up to 20k characters. 

--verbose, -t Print the command line on the standard error output before executing it. 

--version Print the version number of xargs and exit. 

--exit, -x Exit if the size (see the -s option) is exceeded. 

- -Max -procs=max- procs, Run up to max- procs processes at a time the default is 1. If max- procs iS@, xargs will 

-P max- procs run as many processes as possible at a time. Use the -n option with - p; otherwise, chances 


are that only one exec will be done 


SEE ALSO 


find(1L), locate(1L), locatedb(5L), updatedb(1) Finding Files (onlinein info, or printed) 


xauth 


xauth— x authority file utility 


SYNOPSIS 


xauth [ -f authfile ][-vqib ][command arg ... ] 


DESCRIPTION 


The xauth program is used to edit and display the authorization information used in connecting to the x serve. This 
program is usually used to extract authorization records from one machine and merge them in on another (as is the case 
when using remote logins or granting access to other users). Commands (described below) may be entered interactivey, on 
the xauth command line, or in scripts. N ote that this program does not contact the x server. Normally xauth is not used to 
create the authority file entry in the first place xam does that. 


OPTIONS 


The following options may be used with xauth. They may be given individually (for example, -q -i ) or may combined (for 
example, -qi). 


-f authfile This option specifies the name of the authority file to use. By default, xauth will use the file 
specified by the xAUTHORITY environment variable or xauthority in the user’s home 
directory. 

-q This option indicates that xauth should operate quietly and not print unsolicited status 


messages. T his is the default if an xauth command is given on the command line or if the 
standard output isnot directed to a terminal. 

“Vv This option indicates that xauth should operate verbosely and print status messages 
indicating the results of various operations (such as how many records have been read in or 
written out). This is the default if xauth is reading commands from its standard input and 
its standard output is directed to aterminal. 
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COMMANDS 


This option indicates that xauth should ignore any authority file locks. Normally, xauth 
will refuse to read or edit any authority files that have been locked by other programs 
(usually xdm or another xauth). 

This option indicates that xauth should attempt to break any authority file locks before 
proceeding. Use this option only to clean up stale locks. 


T he following commands may be used to manipulate authority files: 


add displ ayname 
protocol name hexkey 


[nJextract filename 
displayname... 


[n]list [displ ayname...] 


[n]merge [filename...] 


remove displayname... 
source filename 

info 

exit 

quit 

help [string] 


? 


DISPLAY NAMES 


An authorization entry for the indicated display using the given protocol and Key data is 
added to the authorization file. T he data is specified as an even-lengthed string of 
hexadecimal digits, each pair representing one octet. T he first digit of each pair gives 

the most significant 4 bits of the octet, and the second digit of the pair gives the least 
significant 4 bits. For example, a 32-character hexkey would represent a 128-bit value. A 
protocol name consisting of just a single period is treated as an abbreviation for 

MIT -MAGIC-COOKIE - 1. 

Authorization entries for each of the specified displays are written to the indicated file If 
the nextract command is used, the entries are written in anumevic format suitable for 
nonbinary transmission (such as secure electronic mail). The extracted entries can be read 
back in using the merge and nmerge commands. 

If the filerame consists of just a single dash, the entries will be written to the standard 
output. 

Authorization entries for each of the specified displays (or all if no displays are named) are 
printed on the standard output. If the nlist command is used, entries will be shown in the 
numeric format used by the nextract command; otherwise, they are shown in a textual 
format. K ey data is always displayed in the hexadecimal format given in the description of 
the add command. 

Authorization entries are read from the specified files and are merged into the authorization 
database, superceding any matching existing entries. If the nmerge command is used, the 
numeric format given in the description of the extract command is used. If a filename 
consists of just a single dash, the standard input will be read if it hasn’t been read before. 
Authorization entries matching the specified displays are removed from the authority file 
The specified file is treated as a script containing xauth commands to execute. Blank lines 
and lines beginning with a pound sign (#) areignored. A single hyphen may be used to 
indicate the standard input, if it hasn’t already been read. 

Information describing the authorization file, whether or not any changes have been made, 
and from where xauth commands are being read is printed on the standard output. 

If any modifications have been made, the authority file is written out (if allowed), and the 
program exits. An end-of-fileis treated as an implicit exit command. 

The program exits, ignoring any modifications. T his may also be accomplished by pressing 
the interrupt character. 

A description of all commands that begin with the given string (or all commands if no 
string is given) is printed on the standard output. 

A short list of the valid commandsis printed on the standard output. 


Display names for the add, [njextract, [n]list, [n]merge,and remove commands use the same format as the DISPLAY 
environment variable and the common -display command-line argument. D isplay-specific information (such as the screen 
number) is unnecessary and will be ignored. Same-machine connections (such as local-host sockets, shared memory, and the 
Internet Protocol hostname localhost) are referred to aS hostname /unix:displaynumber $0 that local entries for different 


machines may be stored in one authority file 


xauth 
EXAMPLE 


The most common use for xauth is to extract the entry for the current display, copy it to another machine, and merge it into 
the user's authority file on the renote machine 


o 


6 Xxauth extract 
- $DISPLAY | rsh otherhost xauth merge - 


ENVIRONMENT 
This xauth program uses the following environment variables: 


XAUTHORITY To get thename of the authority file to use if the -+ option isn’t used. 
HOME To get the user’s home directory if xauTHoRITY isn’t defined. 


FILES 


$HOME/.Xauthority isthe default authority fileif xauTHoRITY isn’t defined. 
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[n]list [displayname...] Authorization entries for each of the specified displays (or all if 
no displays are named) are printed on thestandard output. If 
the nlist command is used, entries will be shown in the 
numeric format used by the nextract command; otherwise, 
they are shown in a textual format. K ey data is always 
displayed in the hexadecimal format given in the description of 
the add command. 

[n]merge [filename...] Authorization entries are read from the specified files and are 
merged into the authorization database, superseding any 
matching existing entries. If the nmerge command is used, the 
numeric format given in the description of the extract 
command is used. If a filavame consists of just a single dash, 
the standard input will be read if it hasn’t been read before. 


remove displayname... Authorization entries matching the specified displays are 
removed from the authority file 
source filename The specified file is treated as a script containing xauth 


commandsto execute. Blank lines and lines beginning with a# 
are ignored. A single dash may be used to indicate the standard 
input, if it hasn’t already been read. 

info Information describing the authorization file, whether or not 
any changes have been made, and from where xauth com- 
mands are being read is printed on the standard output. 

exit If any modifications have been made, the authority file is 
written out (if allowed), and the program exits. An end of file 
is treated as an implicit exit command. 


quit The program exits, ignoring any modifications. T his may also 
be accomplished by pressing the interrupt character. 
help [string] A description of all commands that begin with thegiven string 


(or all commands if no string is given) is printed on the 
standard output. 

? A short list of the valid commandsis printed on the standard 
output. 


DISPLAY NAMES 


Display names for the add, [nJextract, [n]list, [n]merge, and remove commands use the same format as the DISPLAY 
environment variable and the common -display command-line argument. D isplay-specific information (such asthe screen 
number) is unnecessary and will be ignored. Same-machine connections (such aslocal-host sockets, shared memory, and the 
Internet Protocol hostnamel ocal host ) are referred to aS hostname/unix:displaynumber SO that local entries for different 
machines may be stored in one authority file 


EXAMPLE 


The most common use for xauth isto extract the entry for the current display, copy it to another machine, and mege it into 
the user’s authority file on the ranote machine 


% xauth extract 
- $DISPLAY rsh otherhost xauth merge - 
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ENVIRONMENT 


This xauth program uses the following environment variables: 


XAUTHORITY To get thename of the authority file to use if the -+ option 
isn’t used 
HOME To g@ the user’s home directory if xauTHoRITY isn’t defined 
FILES 
$HOME/.Xauthority D efault authority file if xautHority isn’t defined 
BUGS 


Users that have unsecured networks should take care to use encrypted file transfer mechanisms to copy authorization entries 
between machines. Similarly, the m1T-magic-cook1E-1 protocol is not very useful in unsecured environments. Sites that are 
interested in additional security may need to use encrypted authorization mechanisms such as K erberos. 


Spaces are currently not allowed in the protocol name Quoting could be added for the truly perverse 
AUTHOR 
Jim Fulton, MIT X Consortium 
X Verson 11 Release 6 
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xbmtopbm— Convert an X11 or X10 bitmap into a portable bitmap 


SYNOPSIS 

xbmtopbm [bit mapfile] 
DESCRIPTION 

Reads an X11 or X10 bitmap as input. Produces a portable bitmap as output. 
SEE ALSO 

pbmtoxbm(1), pomtox1@bm(1), pom(5) 
AUTHOR 

Copyright (c) 1988 by J ef Poskanzer. 

31 August 1988 

xcmsdb 

xemsdb— D eviceC olor Characterization utility for X Color M anagenent Systen 
SYNOPSIS 


xcemsdb [ -query ][-remove ][-format 32j16j8 ][filename ] 


xclock 
DESCRIPTION 


xemsdb iS used to load, query, or remove device color characterization data stored in properties on the root window of the 
screen as specified in section 7, Device Color Characterization, of the|C CCM . D evice color characterization data (also 
called the D evice Profile) is an integral part of Xlib’s X Color M anagement System (xcms), necessary for proper conversion 
of color specification between device independent and device-dependent forms. xcms uses 3x3 matrices stored in the 
XDCCC_LINEAR_RGB_MATRICES property to convert color specifications between CIEXYZ and RGB Intensity (XcmsRGBi, also 
referred to as linear RGB). xcms then uses display gamma information stored in the xoccc_LINEAR_RGB_CORRECTION property to 
convert color specifications between RGBi and RGB device (XcmsRGB, also referred to as device RGB). 


N ote that xcms allows clients to register function sets in addition to its built-in function set for CRT color monitors. 
Additional function sets may store thar device profile information in other propetties in function set specific format. T his 
utility is unaware of these nonstandard propetties. 

TheASCII readable contents of filename (or the standard input if no input file is given) are appropriately transformed for 
storage in properties, provided the -query or -remove options are not specified. 


OPTIONS 
xemsdb program accepts the following options: 


-query This option attempts to read the XD CCC properties off the 
screen’s root window. If successful, it transforms the data into 
amore readable format, then sends the data to standard out. 


-remove This option attempts to remove the XD CCC properties on the 
screen's root window. 
-format 32j16j8 Specifies the property format (32, 16, or 8 bits per entry) for 


the xDCCC_LINEAR_RGB_CORRECTION propetty. Precision of 
encoded floating-point values increases with the increase in 
bits per entry. The default is 32 bits per entry. 


SEE ALSO 


xprop(1), Xlib documentation 


ENVIRONMENT 


DISPLAY To figure out which display and screen to use 


AUTHOR 
Chuck Adams, Tektronix, Inc., and Al T abayoyon, SynC hromatics, Inc. (added multivisual support) 


X Verdon 11 Release 6 


xclock 


xclock— Analog/digital clock for X 


SYNOPSIS 
xclock [ -help ][-analog ][-digital ][-chime ][-hd color ][-hl color ] 
[-update seconds ][-padding number ] 
DESCRIPTION 


The xclock program displays the time in analog or digital form. T he time is continuously updated at a frequency which may 
be specified by the user. 
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OPTIONS 


xclock accepts all of the standard X Toolkit command-line options along with the additional options listed here: 


-help 

-analog 

-digital OF -d 

-chime 

-hands color (OF -hd color) 


-highlight color (Of -hl color) 


-update seconds 


-padding number 


X DEFAULTS 


This option indicates that a brief summary of the allowed 
options should be printed on the standard error. 

This option indicates that a conventional 12-hour clock face 
with tick marks and hands should be used. T hisis the default. 
This option indicates that a 24-hour digital clock should be 
used. 
This option indicates that the clock should chime once on the 
half hour and twice on the hour. 

This option specifies the color of the handson an analog 
clock. The default is black. 

This option specifies the color of the edges of the hands on an 
analog clock, and is only useful on color displays. T he default 
iS black. 
This option specifies the frequency in seconds at which xclock 
should update its display. | f the clock is obscured and then 
exposed, it will be updated immediately. A value of 30 seconds 
or less will enable a second hand on an analog clock. The 
default is 6a seconds. 

This option specifies the width in pixds of the padding 
between the window border and clock text or picture The 
default is 10 on adigital clock and 8 on an analog clock. 








This program uses the Clock widget. It understands all of the core resource names and classes as wall as: 


width (class Width) 


height (class Height) 


update (class Interval) 


foreground (class Foreground) 


hands (class Foreground) 


highlight (class Foreground) 


analog (class Boolean) 


chime (class Boolean) 


Specifies the width of the clock. The default for analog clocks 
is 164 pixels, the default for digital clocks is whatever is needed 
to hold the clock when displayed in the chosen font. 

Specifies the height of the clock. The default for analog clocks 
is 164 pixels, the default for digital clocks is whatever is needed 
to hold the clock when displayed in the chosen font. 

Specifies the frequency in seconds at which the time should be 
redisplayed. 

Specifies the color for the tick marks. T he default is depends 
on whether reverseVideo is specified. If reverseVideo is 
specified, the default is iwnite; otherwise the default is black. 
Specifies the color of the insides of the clock’s hands. The 
default depends on whether reverseVideo is specified. If 
reverseVideo iS Specified, the default is white; otherwise, the 
default is black. 

Specifies the color used to highlight the clock’s hands. T he 
default depends on whether reverseVideo is specified. If 
reverseVideo iS Specified, the default is white; otherwise the 
default is black. 

Specifies whether or not an analog clock should be used 
instead of a digital one. The default is True. 

Specifies whether or not a bell should be rung on the hour and 
half hour. 
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padding (class Margin) Specifies the amount of internal padding in pixels to be used. 
The default is 8. 
font (class Font) Specifies the font to be used for the digital clock. N ote that 


variable width fonts currently will not always display correctly. 


WIDGETS 
In order to specify resources, it is useful to Know the hierarchy of the widgets which compose xclock. In the following 
notation, indentation indicates hierarchical structure. T he widget class name is given first, followed by the widget instance 
name 


XClock xclock 
Clock clock 


ENVIRONMENT 
DISPLAY To get the default host and display number 
XENVIRONMENT To get thename of a resource file that overrides the global 
resources stored in the RESOURCE_MANAGER property 
FILES 
<XRoott/1ib/X11/app-defaults /XClock Specifies required resources 
SEE ALSO 
x(1), xrdb(1), time(3C ) 
BUGS 


xclock believes the system clock. 
W hen in digital mode, the string should be centered automatically. 


AUTHORS 
Tony D dla Fera (MIT -Athena, DEC), D aveM ankins (MIT -Athena, BBN ), and Ed M oy (UC Berkdey) 
X Version 11 Release 6 
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xclipboard— X clipboard client 


SYNOPSIS 


xclipboard [ -toolkitoption ... ] [ -w ][-nw ] 


DESCRIPTION 


The xclipboard program is used to collect and display text selections that are sent to the Clipboard by other clients. It is 
typically used to save Clipboard sdections for later use. It stores each Clipboard selection as a separate string, each of which 
can be selected. Each time Clipboard is asserted by another application, xclipboard transfers the contents of that selection to 
anew buffer and displaysit in the text window. Buffers are never automatically deleted, so you'll want to use the delete 
button to get rid of useless items. 


Since xclipboard uses a T ext W idget to display the contents of the clipboard, text sent to the Clipboard may be reselected for 
usein other applications. xclipboard also responds to requests for the Clipboard selection from other clients by sending the 
entire contents of the currently displayed buffer. 
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An xclipboard window has the following buttons across the top: 


quit 
ddede 


new 
save 


next 
previous 


OPTIONS 


W hen this button is pressed, xclipboard exits. 


W hen this button is pressed, the current buffer is deleted and 
the next one displayed. 


Creates a new buffer with no contents. U seful in constructing 
anew Clipboard selection by hand. 


Displays a File Save dialog box. Pressing the Accept button 
saves the currently displayed buffer to the file specified in the 
text field. 


Displays the next buffer in the list. 
Displays the previous buffer. 


The xclipboard program accepts all of the standard X Toolkit command-line options as well as the following: 


-W 


-nw 


WIDGETS 


This option indicates that lines of text that are too long to be 
displayed on onelinein the clipboard should wrap around to 
the following lines. 


This option indicates that long lines of text should not wrap 
around. T hisis the default behavior. 


In order to specify resources, it is useful to Know the hierarchy of the widgets which compose xclipboard. In the following 
notation, indentation indicates hierarchical structure. T he widget class name is given first, followed by the widget instance 


name. 


XClipboard xclipboard 

Form form 
Command Quit 
Command delete 
Command new 
Command Save 
Command next 
Command prev 
Label index 
Text text 

TransientShell fileDialogShell 
Dialog fileDialog 
Label label 
Command accept 
Command cancel 
Text value 

TransientShell failDialogShell 
Dialog failDialog 
Label label 
Command continue 


SENDING/RETRIEVING CLIPBOARD CONTENTS 


Text is copied to the Clipboard whenever a client asserts ownership of the Clipboard selection. T ext is copied from the 
Clipboard whenever a client requests the contents of the Clipboard selection. Examples of event bindings that a user may 
wish to include in a resource configuration file to use the Clipboard are 


*VT100.Translations: #override \ 
<Btn3Up>: select-end(CLIPBOARD) \n\ 


xconsole 597 


<Btn2Up>: insert-selection(PRIMARY,CLIPBOARD) \n\ 
<Btn2Down>: ignore () 


SEE ALSO 
x(1), xcutse1(1), xterm(1), individual client documentation for how to make a selection and send it to the Clipboard. 
ENVIRONMENT 
DISPLAY To get the default host and display number 
XENVIRONMENT To get thename of a resource file that overrides the global 
resources stored in the RESOURCE_MANAGER property 
FILES 
<XRoot>/1ib/X11/app-defaults/XClipboard Specifies required resources 
AUTHOR 


Ralph R. Swick (DEC/MIT Project Athena), Chris D. Peterson (MIT X Consortium), Keith Packard (MIT X Consortium) 
X Verson 11 Release 6 
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xconsole— M onitor system console messages with X 


SYNOPSIS 
xconsole [-toolkitoption ...] [-file file-name] [-notify] [-stripNonprint] [-daemon] [-verbose] 
[ -exitOnFail] 
DESCRIPTION 
The xconsole program displays messages that are usually sent to /dev/console. 
OPTIONS 
xconsole accepts all of the standard X Toolkit command-line options along with the additional options listed hee 
-file file-name To monitor some other device, use this option to specify the 


device name. This does not work on regular files as they are 
always ready to be read from. 

-notify, -nonotify W hen new data are recaved from the console and the notify 
option is set, the icon name of the application has * appended, 
so that it is evident even when the application is iconified. - 
notify is the default. 


-daemon This option causes Xconsole to place itself in the background, 
using fork/exit. 

-verbose W hen set, this option directs xconsole to display an informa- 
tive message in the first line of the text buffer. 

-exitOnFail When set, this option directs xconsole to exit when it is unable 


to redirect the console output. 


X DEFAULTS 
This program uses the Athena T ext widget, look in the Athena W idget Set documentation for controlling it. 
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WIDGETS 
In order to specify resources, it is useful to Know the hierarchy of the widgets that compose xconsole. In the following 
notation, indentation indicates hierarchical structure. T he widget class name is given first, followed by the widget instance 
name 


XConsole xconsole 
XConsole text 


ENVIRONMENT 
DISPLAY To get the default host and display number. 
XENVIRONMENT To get thename of a resource file that overrides the global 
resources stored in the RESOURCE_MANAGER propetty. 
FILES 
<XRoot>/1ib/X11/app-defaults/XConsole Specifies required resources 
SEE ALSO 
x(1), xrdb(1), Athena T ext widget 
AUTHOR 


Keith Packard (MIT X Consortium) 
X Version 11 Release 6 
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xcutsel— Interchange between cut buffer and selection 


SYNOPSIS 


xcutsel [ -toolkitoption ...] [-selection selection] [-cutbuffer number ] 


DESCRIPTION 


The xcutsel program is used to copy the current selection into a cut buffer and to make a selection that contains the current 
contents of the cut buffer. It acts as a bridge between applications that don’t support selections and those that do. 


By default, xcutse1 will use the sdection named primary and thecut buffer cut_surrero. Either or both of these can be 
overridden by command-line arguments or by resources. 


An xcutse1 window has the following buttons: 


quit W hen this button is pressed, xcutse1 exits. Any sdections hdd 
by xcutsel are automatically released. 

copy PRIMARY to 0 W hen this button is pressed, xcutse1 copies the current 
selection into the cut buffer. 

copy @ to PRIMARY W hen this button is pressed, xcutsel converts the current 


contents of the cut buffer into the sdection. 


The button labels reflect the sdection and cut buffer selected by command-line options or through the resource database. 


When the copy 0 to PRIMARY button is activated, the button will remain inverted as long as xcutse1 remains the owner of 
the selection. This serves to remind you which client owns the current selection. N ote that the value of the sdection remains 
constant; if the cut buffer is changed, you must again activate the copy button to retrieve the new value when desired. 
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-selection name This option specifies the name of the sdection to use The 
default is primary. T he only supported abbreviations for this 
option are -select, -sel, and -s, asthe standard toolkit option 
-selectionTimeout hasa similar name. 

-cutbuffer number This option specifies the cut buffer to use. T he default is 
cutbuffer Q. 


OPTIONS 


Xcutsel accepts all of the standard X Toolkit command-line options as well as the following: 


X DEFAULTS 
This program accepts all of the standard X Toolkit resource names and classes as well as the following: 
selection (class Selection) This resource specifies the name of the selection to use. The 
default is PRIMARY. 
cutBuffer (class CutBuffer) This resource specifies the number of the cutbuffer to use 


The default is 0. 


WIDGET NAMES 

The following instance names may be used when user configuration of the labels in them is desired: 

sel-cut (class Command) Thisis the “copy SELECTION to BUFFER” button. 

cut-sel (class Command) Thisis the “copy Burrer to SELECTION” button. 

quit (class Command) Thisis the “quit” button. 
SEE ALSO 

X(1), xclipboard(1), xterm(1), text widget documentation, individual client documentation for how to make a selection. 
BUGS 

There is no way to change the name of the sdection or the number of the cut buffer while the program is running. 
AUTHOR 


Ralph R. Swick (DEC/MIT Project Athena) 
X Version 11 Release 6 
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xdm— X Display M anager with support for XD M CP, host chooser 
SYNOPSIS 


xdm [ -config configuration_file ][-nodaemon ][-debug debug_level ] 
[-error error_log_file ][-resources resource_file ][-server server_entry ] 
[-sessionsession program] 


DESCRIPTION 


xdm Manages a collection of X displays, which may be on the local host or remote servers. T he design of xdm was guided by 
the needs of X terminals as well asthe X Consortium standard xomcp, the X Display M anager Control Protocol. xdm provides 
services similar to those provided by init, getty, and login on character terminals: prompting for login name and password, 
authenticating the user, and running a session. 
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A sesson is defined by the lifetime of a particular process; in the traditional character-based terminal world, it is the user’s 
login shell. In the xdm context, it is an arbitrary session manager. T his is because in a windowing environment, a user’s login 
shell process does not necessarily have any terminal-like interface with which to connect. When areal session manager is not 
available, a window manager or terminal emulator is typically used as the session manager, meaning that termination of this 
process terminates the user’s session. 


W hen the session is terminated, xam resets the X server and (optionally) restarts the whole process. 


W hen xam receives an Indirect query viaXDM CP, it can run a chooser process to perform an XD M CP BroadcastQ uery (or 
an XDMCP Query to specified hosts) on behalf of the display and offer a menu of possible hosts that offer XD M CP display 
managenent. T his feature is useful with X terminals that do not offer a host menu themsdves. 


Because xdm provides the first interface that users will see, it is designed to be simple to use and easy to customize to the needs 
of a particular site. xdm has many options, most of which have reasonable defaults. Browse through the various sections of this 
manual, picking and choosing the things you want to change. Pay particular attention to the “Session Program” subsection, 
which will describe how to set up the style of session desired. 


OVERVIEW 


xdm ishighly configurable, and most of its behavior can be controlled by resource files and shdl scripts. The names of these 
files themselves are resources read from the file xdm-config or the file named by the -config option. 


xdm Offers display management two different ways. It can manage X servers running on thelocal machine and specified in 
Xservers, and it can manage remote X servers (typically X terminals) using xoucr (the XDM Control Protocol) as specified in 
the xaccess file 


The resources of the X clients run by xam outside the user’s session, including xdm’s own login window, can be affected by 
setting resources in the xresources file 


For X terminals that do not offer a menu of hosts to ge@t display management from, xam can collect willing hosts and run the 
chooser program to offer the user a menu. For X displays attached to a host, this step is typically not used, as the local host 
does the display managenent. 





After resetting the X server, xdm runs the xsetup script to assist in setting up the screen the user sees along with the xlogin 
widget. 


When the user logs in, xdm runs the xstartup script as root. 


Then xam runs the xsession script as the user. T his system session file may do some additional startup and typically runsa 
script in the user’s home directory. When the xsession script exits, the session is over. 


At the end of the session, thexreset script is run to clean up, the X server is reset, and the cycle starts over. 


The file /usr/x11R6/1ib/Xx11/xdm/xdm-errors Will contain error messages from xam and anything output to stderr by Xsetup, 
Xstartup, Xsession, OF Xreset. When you have trouble getting xdm working, check this file to see if xam has any clues to the 
trouble. 


OPTIONS 
All of these options, except -config itself, specify values that can also be specified in the configuration file as resources. 


-config configuration file N ames the configuration file, which specifies resources to 
control the behavior of xam. <XRoot>/1ib/X11/xdm/xdm-config IS 
the default. See the subsection called “C onfiguration File.” 


-nodaemon Specifies false as the value for the DisplayManager . daemonMode 
resource. T his suppresses the normal daemon behavior, which 
is for xdm to close all file descriptors, disassociate itself from the 
controlling terminal, and put itself in the background when it 
first starts up. 
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-debug debug | evel Specifies the numeric value for the DisplayManager.debugLevel 
resource. A non-zero value causes xdm to print lots of 
debugging statements to the terminal; it also disables the 
DisplayManager .daemonModeresource, forcing xdm to run 
synchronously. T 0 interpret these debugging messages, a copy 
of the source code for xdm is almost a necessity. No attempt has 
been made to rationalize or standardize the output. 

-error error_log file Specifies the value for the DisplayManager.errorLogFile 
resource. This file contains errors from xam as well as anything 
written to stderr by the various scripts and programs run 
during the progress of the session. 


-resources resource file Specifies the value for the DisplayManager*resources resource 
This file is loaded using xrdb to specify configuration 
parameters for the authentication widge. 

-server server_entry Specifies the value for the DisplayManager.servers resource 
See the subsection “Local Server Specification” for a descrip- 
tion of this resource 

-udpPort port _number Specifies the value for the DisplayManager.requestPort 
resource. T his sets the port numbe,, which xam will monitor 
for XDMCP requests. AsXD MCP uses the registered well- 
known UDP port 177, this resource should not be changed 


except for debugging. 

-session session program Specifies the value for the DisplayManager*session resource 
This indicates the program to run as the session after the user 
has logged in. 

-xrm resource specification Allows an arbitrary resource to be specified, asin most X 


Toolkit applications. 


RESOURCES 


At many stages the actions of xdm can be controlled through the use of its configuration file, which isin the X resource 
format. Some resources modify the behavior of xdm on all displays, while others modify its behavior on a single display. 

W here actions relate to a specific display, the display name is inserted into the resource name between Display -Manager and 
the final resource name segment. 


For local displays, the resource name and class are as read from thexservers file. 


For remote displays, the resource name is what thenetwork address of the display resolves to. See the removeDomain resource 
Thename must match exactly; xam is not aware of all the network aliases that might reach a given display. If the name resolve 
fails, the address is used. T he resource class is as sent by the display in theXD M CP M anage request. 


Because the resource manager uses colons to separate the name of the resource from its value and dots to separate resource 
name parts, xam substitutes underscores for both dots and colons when generating the resource name. F or example 
DisplayManager.expo x org @.startup isthename of the resource that defines the startup shall file for the expo.x.org:0 
display. 


DisplayManager.servers This resource ether specifies a filename full of server entries, 
one per line (if the value starts with a slash), or a single server 
entry. See the subsection “Local Server Specification” for the 
détails. 

DisplayManager.requestPort This indicates the UD P port number that xam uses to listen for 
incoming XD M CP requests. U nless you need to debug the 
system, leave this with its default value of 177. 
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DisplayManager. 


DisplayManager. 


DisplayManager. 


DisplayManager. 


DisplayManager. 


DisplayManager. 


DisplayManager. 


DisplayManager. 


errorLogFile 


debugLevel 


daemonMode 


pidFile 


lockPidFile 


authDir 


autoRescan 


removeDomainname 


keyFile 


Error output is normally directed at the system console. To 
redirect it, set this resource to a filename A method to send 
these messages to syslog should be developed for systems that 
support it; however, the wide variety of interfaces precludes 
any system-independent implementation. This file also 
contains any output directed to stderr by the xsetup, Xstartup, 
Xsession, and Xreset files, so it will contain descriptions of 
problems in those scripts as well. 


If the integer value of this resource is greater than zero, reams 
of debugging information will be printed. It also disables 
daemon mode, which would redirect the information into the 
bit-bucket, and allows nonroot users to run xdm, which would 
normally not be useful. 


Normally, xam attempts to make itself into a daemon process 
unassociated with any terminal. This is accomplished by 
forking and leaving the parent process to exit, then closing file 
descriptors and releasing the controlling terminal. In some 
environments thisis not desired (in particular, when 
debugging). Setting this resource to false will disable this 
feature. 

The filename specified will be created to contain an ASCII 
representation of the process-id of the main xdm process. xdm 
also uses file locking on this file to attempt to diminate 
multiple daemons running on the same machine, which would 
cause quite a bit of havoc. 

This is the resource which controls whether xdm uses file 
locking to keep multiple display managers from running 
amok. On System V, this uses the lock¢ library call, while on 
BSD it uses flock. 

This names a directory in which xdm stores authorization files 
while initializing the session. T he default value is y. 

This Boolean controls whether xam rescans the configuration, 
servers, access control and authentication keys files after a 
session terminates and the files have changed. By default it is 
true. You can force xdm to reread these files by sending a 
sicHup to the main process. 


W hen computing the display name for xowcp clients, the name 
resolver will typically create a fully qualified hostname for the 
terminal. As this is sometimes confusing, xam will renove the 
domain name portion of the hostname if it is the same as the 
domain name of the local host when this variable is set. By 
default the value is true. 

XDM-AUTHENTICATION-1 style XD M CP authentication requires 
that a private key be shared between xam and the terminal. T his 
resource specifies the file containing those values. Each entry 
in thefile consists of a display name and the shared key. By 
default, xam does not include support for xDM-AUTHENTICATION-1, 
as it requires pes, which is not generally distributable because 
of U nited States export restrictions. 
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DisplayManager.accessFile To prevent unauthorized XD M CP serviceand to allow 
forwarding of XDMCP IndirectQuery requests, this file 
contains a database of hostnames that are either allowed direct 
access to this machine, or havea list of hosts to which queries 
should be forwarded to. The format of this file is described in 
the subsection “XD MCP Access Control.” 

DisplayManager.exportList A list of additional environment variables, separated by 


whitespace, to pass on to the xsetup, Xstartup, Xsession,and 
Xreset programs. 


DisplayManager.randomFile A file to checksum to generate the seed of authorization keys. 
This should be a file that changes frequently. T he default is 
/dev/mem. 

DisplayManager.greeterLib On systems that support a dynamically loadable greeter library, 


the name of the library. D efault is <xRoot>/1ib/x11/xdm/ 

libXdmGreet .so. 

DisplayManager.choiceTimeout N umber of seconds to wait for display to respond after user 
has selected a host from the chooser. If the display sends an 
XDMCP IndirectQuery within this time the request is 
forwarded to the chosen host. O therwise, it is assumed to be 
from anew session and the chooser is offered again. D efault 
iS 15. 

DisplayManager.DI SPLAY .resources This resource specifies the name of the file to be loaded by 
xrdb as the resource database onto the root window of screen 0 
of the display. The xsetup program, the Login widget, and 
chooser Will use the resources set in this file. T his resource 
database is loaded just before the authentication procedure is 
started, so it can control the appearance of the login window. 
See the subsection “Authentication Widget,” which describes 
the various resources that are appropriate to place in this file 
Thereis no default value for this resource, but <xRoot>/1ib/ 
X11/xdm/Xresources iS the conventional name. 

DisplayManager.DI SPLAY .chooser Specifies the program run to offer ahost menu for Indirect 

queries redirected to the special hostname cHooseR. <XxRoot> 

/1ib/X11/xdm/chooser is the default. See the subsections 

“XDM CP Access Control” and “chooser.” 





DisplayManager.DI SPLAY .xrdb Specifies the program used to load the resources. By default, 
xdm USES <XRoot>/bin/xrdb. 

DisplayManager.DI SPLAY .cpp This specifies the name of the C preprocessor that is used by 
xrdb. 

DisplayManager.DI SPLAY .setup This specifies a program that is run (as root) before offering 


the Login window. T his may be used to change the appearance 
of the scren around the Login window or to put up other 
windows (for example you may want to run xconsole here). 
By default, no program is run. The conventional name for a 
file used here is xsetup. See the subsection “Setup Program.” 

DisplayManager.DI SPLAY .startup This specifies a program that is run (as root) after the 
authentication process succeeds. By default, no program is run. 
Theconventional name for a file used here is Xstartup. See the 
subsection “Startup Program.” 

DisplayManager.DI SPLAY .session This specifies the session to be executed (not running as root). 
By default, <xRoot>/bin/xterm iSrun. The conventional name 
iS Xsession. See the subsection “Session Program.” 
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DisplayManager 


DisplayManager 
DisplayManager 
DisplayManager 
DisplayManager 


«DISPLAY. 


-DISPLAY. 
-DISPLAY. 
«DISPLAY. 
-DISPLAY. 


reset 


openDelay, 
openRepeat, 
oOpenTimeout, 
startAttempts 


DisplayManager.DI SPLAY .pingInterval, 
DisplayManager .DI SPLAY. pingTimeout 


DisplayManager 


-DISPLAY. 


terminateServer 


DisplayManager.DI SPLAY .userPath 


DisplayManager 
systemPath 


-DISPLAY. 


This specifies a program which is run (as root) after the session 
terminates. Again, by default, no program isrun. The 
conventional name is Xreset. See the subsection “Reset 
Program.” 


T hese numeric resources control the behavior of xdm when 
attempting to open intransigent servers. openDelay isthe length 
of the pause (in seconds) between successive attempts, 
openRepeat iSthenumber of attempts to make openTimeout iS 
the amount of time to wait while actually attempting the open 
(that is, the maximum time spent in the connect(2) system 

call) and startattempts isthe number of times this entire 
process is done before giving up on the server. After openRepeat 
attempts have been made, or if openTimeout seconds elapse in 
any particular attempt, xam terminates and restarts the server, 
attempting to connect again. T his process is repeated 
startAttempts times, at which point the display is declared 
dead and disabled. Although this behavior may seem arbitrary, 
it has been empirically devdoped and works quite well on 
most systems. The default values ares for openDelay, 5 for 
openRepeat, 30 for openTimeout and 4 for startAttempts. 


To discover when remote displays disappear, xdm 

occasionally pingsthen, using an X connection and xsync 
Calls. pingInterval specifies the time (in minutes) between 
each ping attempt, pingTimeout specifies the maximum 
amount of time (in minutes) to wait for the terminal to 
respond to the request. If the terminal does not respond, the 
session is declared dead and terminated. By default, both are 
set to 5 minutes. If you frequently use X terminals that can 
become isolated from the managing host, you might want to 
increase this value. The only worry is that sessions will 
continue to exist after the terminal has been accidentally 
disabled. xdm will not ping local displays. Although it would 
seem harmless, it is unpleasant when the workstation session is 
terminated as a result of the server hanging for N FS service 
and not responding to the ping. 

This Boolean resource specifies whether the X server should be 
terminated when a session terminates (instead of resetting it). 
This option can be used when the server tends to grow 
without bound over time, in order to limit the amount of time 
the server is run. The default value is false. 

xdm sets the PATH environment variable for the session to this 
value. It should be a colon separated list of directories; see 
sh(1) for a full description. : /bin: /usr/bin: /usr/X11R6/bin 
:/usr/ucb isacommon setting. The default value can be 
specified at build timein thex system configuration file with 
DefaultUserPath. 

Xdm sets the PATH environment variable for the startup and reset 
scripts to the value of this resource. T he default for this 
resource is specified at build time by the DefaultSystem-Path 
entry in the system configuration file /etc:/bin:/usr/bin 
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: /usr/X11R6/bin:/usr/ ucb isacommon choice N ote the 
absence of (.) from this entry. This is a good practice to follow 
for root; it avoids many common Trojan H orse system 
penetration schemes. 


DisplayManager.DI SPLAY. Xdm Sets the SHELL environment variable for the startup and 

systemShell reset scripts to the value of this resource. It is /bin/sh by 
default. 

DisplayManager.DI SPLAY If the default session fails to execute, xam will fall back to this 

failsafeClient program. T his program is executed with no arguments, but 


executes using the same environment variables as the session 
would have had. (See the subsection “Session Program.”) By 
default, <xRoot>/bin/xterm is used. 


DisplayManager.DI SPLAY .grabServer, To improve security, this grabs the server and keyboard while 

DisplayManager.DI SPLAY. grabTimeout xdm reading thelogin name and password. T he grabServer resource 
specifies if the server should be held for the duration of the 
name/password reading. When false, the server is ungrabbed 
after the keyboard grab succeeds; otherwise, the server is 
grabbed until just before the session begins. T he default is 
false. The grabTimeout resource specifies the maximum time 
xdm will wait for the grab to succeed. T he grab may fail if some 
other client has the server grabbed, or possibly if the network 
latencies are very high. T his resource has a default value of 3 
seconds; you should be cautious when raising it, asa user can 
be spoofed by a look-alike window on the display. If the grab 
fails, xdm kills and restarts the server (if possible) and the 


session. 
DisplayManager.DI SPLAY .authorize, authorize iS a Boolean resource that controls whether xdm 
DisplayManager.DI SPLAY .authName generates and uses authorization for the local server connec- 


tions. If authorization is used, authName is alist of authorization 
mechanisms to use, separated by whitespace XDM CP 
connections dynamically specify which authorization 
mechanisms are supported, so authName is ignored in this case. 
W hen authorize is set for a display and authorization is not 
available, the user isinformed by having a different message 
displayed in the Login widget. By default, authorize is true. 
authName iS MIT -MAGIC-COOKIE-1, OF, if XDM-AUTHORIZATION-1 iS 
available, XDM-AUTHORIZATION-1 MIT-MAGIC-COOKIE-1. 

DisplayManager.DI SPLAY .authFile This file is used to communicate the authorization data from 
xdm to theserver, using the -auth server command-line option. 
It should be kept in a directory that is not world-writable as it 
could easily be removed, disabling the authorization mecha- 
nism in the server. 


DisplayManager.DI SPLAY. If set to false, disables the use of the unsecureGreeting in the 

authComplain login window. See the subsection “Authentication W idget.” 
The default is true. 

DisplayManager.DI SPLAY. The number of the agnal xam sends to reset the server. 

resetSignal See the subsection “Controlling the Server.” The default is 1 
(SIGHUP). 

DisplayManager.DI SPLAY. The number of the signal xam sends to terminate the server. See 

termSignal the subsection “Controlling the Server.” T he default is 15 


(SIGTERM). 


Part |: User Commands 


DisplayManager.DI SPLAY. Theoriginal implenentation of authorization in the sample 

resetForAuth server reread the authorization file at server reset time, instead 
of when checking the initial connection. As xdm generates the 
authorization information just before connecting to the 
display, an old server would not get up-to-date authorization 
information. T his resource causes xdm to send staHup to the 
server after setting up the file, causing an additional server reset 
to occur, during which time the new authorization information 
will be read. T he default is false, which will work for all MIT 


servers. 
DisplayManager.DI SPLAY. When xdm is unable to write to the usual user authorization file 
userAuthDir ($HOME/.Xauthority), it creates a unique filename in this 


directory and points the environment variable xautHoRITY at 
the created file It uses /tmp by default. 


CONFIGURATION FILE 


First, the xdm configuration file should be set up. M ake a directory (usually <xRoot>/1ib/x11/xdm, where <xRoot> refers to the 
root of the X11 install tree) to contain all of the relevant files. In the examples that follow, /usr/x11R6 is used as the value of 
<XRoot>. 

H ere is areasonable configuration file which could be named xdm-contig: 

DisplayManager.servers: /usr/X11R6/1lib/X11/xdm/Xservers 

DisplayManager.errorLogFile: /usr/X11R6/1lib/X11/xdm/xdm-errors 

DisplayManager*resources: /usr/X11R6/1lib/X11/xdm/Xresources 

DisplayManager*startup: /usr/X11R6/1lib/X11/xdm/Xstartup 

DisplayManager*session: /usr/X11R6/1lib/X11/xdm/Xsession 

DisplayManager.pidFile: /usr/X11R6/1ib/X11/xdm/xdm-pid 

DisplayManager. @.authorize: true 

DisplayManager*authorize: false 


N ote that this file mostly contains references to other files. N ote also that some of the resources are specified with * 
separating the components. T hese resources can be made unique for each different display, by replacing the * with the 
display name, but normally this is not very useful. See the “Resources” section for a complete discussion. 


XDMCP ACCESS CONTROL 


The database file specified by the DisplayManager.accessFile provides information which xdm uses to control access from 
displays requesting XD M CP service This file contains three types of entries: entries that control the response to Direct and 
Broadcast queries, entries that control the response to Indirect queries, and macro definitions. 


The format of the Direct entries is simple, ather a hostname or a pattern, which is distinguished from a hostname by the 
inclusion of one or more metacharacters (* matches any sequence of 0 or more characters, and 7 matches any single 
character) which are compared against the hostname of the display device. If the entry is ahostname, all comparisons are 
done using network addresses, so any name which converts to the correct network address may be used. For patterns, only 
canonical hostnames are used in the comparison, so ensure that you do not attempt to match aliases. Preceding either a 
hostname or a pattern with a! character causes hosts that match that entry to be excluded. 


An Indirect entry also contains a hostname or pattern, but follows it with a list of hostnames or macros to which indirect 
queries should be sent. 


A macro definition contains a macro name and alist of hostnames and other macros that the macro expands to. To 
distinguish macros from hostnames, macro names start with a% character. M acros may be nested. 


Indirect entries may also specify to have xdm run chooser to offer a menu of hosts to connect to. See the subsection 
“chooser.” 
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W hen checking access for a particular display host, each entry is scanned in turn and thefirst matching entry determines the 
response. Direct and Broadcast entries are ignored when scanning for an Indirect entry and vice versa. 


Blank lines are ignored, # istreated as a comment delimiter causing the rest of that line to be ignored, and \newline causes the 
newline to be ignored, allowing indirect host lists to span multiple lines. H ere is a sample xaccess file 

# 

# Xaccess - XDMCP access control file 

# 

# 

# Direct/Broadcast query entries 

# 

!xtra.lcos.mit.edu # disallow direct/broadcast service for xtra 

bambi.ogi.edu # allow access from this particular display 

.lcs.mit.edu # allow access from any display in LCS 

# 

# Indirect query entries 

# 

%HOSTS expo.lcs.mit.edu xenon.1lcs.mit.edu \ 

excess.lcs.mit.edu kanga.lcs.mit.edu extract.lcs.mit.edu xenon.lcs.mit.edu #force extract to contact xenon 
!xtra.lcs.mit.edu dummy #disallow indirect access 

.lcs.mit.edu “HOSTS #all others get to choose 


chooser 


For X terminals that do not offer a host menu for use with Broadcast OF Indirect queries, the chooser program can do this 

for them. In the xaccess file, specify cHooser as the first entry in the tndirect host list. chooser will send a Query request to 
each of the remaining hostnames in the list and offer amenu of all the hosts that respond. 

The list may consist of the word Broapcasr, in which case chooser will send a Broadcast instead, again offering a manu of all 
hosts that respond. N ote that on some operating systems, U D P packets cannot be broadcast, so this feature will not work. 


Example xaccess file using chooser: 

extract.1cs.mit.edu CHOOSER %HOSTS #offer a menu of these hosts 

xtra.lcs.mit.edu CHOOSER BROADCAST #offer a menu of all hosts 

The program to use for chooser is specified by the DisplayManager.DI SPLAY .chooser resource. For more flexibility at this step, 
the chooser could bea shdl script. chooser is the session manager here it isrun instead of a child xam to manage the display. 
Resources for this program can be put into the file named by DisplayManager.DI SPLAY . resources. 


W hen the user selects a host, chooser prints the host chosen, which isread by the parent xdm, and exits. xdm closes its 
connection to the X server, and the server resets and sends another Indirect XDM CP request. xdm remembers the user’s 
choice (for DisplayManager. choiceTimeout Seconds) and forwards the request to the chosen host, which starts a session on that 
display. 


LOCAL SERVER SPECIFICATION 


The resource DisplayManager.servers gives a server specification or, if the values starts with a slash (/), thename of a file 
containing server specifications, one per line. 

Each specification indicates a display which should constantly be managed and which is not using XD M CP. This method is 
used typically for local servers only. If the resource or the file named by the resource is empty, xdm will offer XD MCP service 
only. 

Each specification consists of at least three parts: a display name, a display class, a display type, and (for local servers) a 
command line to start the server. A typical entry for local display number 0 would be 

:Q@ Digital-QV local /usr/X11R6/bin/X :0 
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608 
The display types are 
Local local display: xam must run theserver 
Foreign remote display: xdm opens an X connection to a running server 
The display name must be something that can be passed in the -display option to an X program. This string is used to 
generate the display-specific resource names, so be careful to match the names (for example, use :0 Sun-CG3 local /usr 
/X11R6/bin/x :@ instead Of localhost:® Sun-CG3 local /usr/X11R6/bin/X :@ if your other resources are specified as 
DisplayManager._@.session). T he display class portion is also used in the display-specific resources, as the class of the 
resource. T his is useful if you havea large collection of similar displays (such as. a corral of X terminals) and would like to set 
resources for groups of then. When using XDM CP, the display is required to specify the display class, so the manual for 
your particular X terminal should document the display class string for your device If it doesn’t, you can run xdm in debug 
mode and look at the resource strings that it generates for that device, which will include the class string. 
W hen xam starts a session, it sets up authorization data for the server. For local servers, xdm passes -auth filename on the 
server's command line to point it at its authorization data. For XDM CP servers, xdm passes the authorization data to the 
server via the accept XDM CP request. 
RESO URCES FILE 
The xresources file is loaded onto the display as a resource database using xrdb. As the authentication widget reads this 
database before starting up, it usually contains parameters for that widget: 
xlogin*login. translations: #override\ 
Ctrl<Key>R: abort-display()\n\ 
<Key>F1: set-session-argument(failsafe) finish-field()\n\ 
<Key>Return: set-session-argument() finish-field() 
xlogin*borderWidth: 3 
xlogin*greeting: CLIENTHOST 
#ifdef COLOR 
xlogin*greetColor: CadetBlue 
xlogin*failColor: red 
#endif 
Please note the translations entry; it specifies a few new translations for the widget that allow users to escape from the default 
session (and avoid troubles that may occur in it). N ote that if #override isnot specified, the default translations are removed 
and replaced by the new value, not a very useful result as some of the default translations are quite useful (such as <key>: 
insert-char (), which responds to normal typing). 
This file may also contain resources for the setup program and chooser. 
SETUP PROGRAM 


The xsetup fileis run after the server is reset, but before the Login window is offered. T he file is typically a shell script. It is 
run as root, so you should be careful about security. This is the place to change the root background or bring up other 
windows that should appear on the screen along with the Login widget. 


In addition to any specified by DisplayManager.exportList, the following environment variables are passed: 


DISPLAY The associated display name 

PATH The value of DisplayManager.DI SPLAY .systemPath 
SHELL The value of DisplayManager.DI SPLAY .systemShel1 
XAUTHORITY M ay be set to an authority file 


N ote that since xam grabs the keyboard, any other windows will not be able to receive keyboard input. T hey will be able to 
interact with the mouse, however’; beware of potential security holes here. If DisplayManager.D! SPLAY .grabServer iS Set, Xsetup 
will not be able to connect to the display at all. Resources for this program can be put into the file named by 
DisplayManager.DI SPLAY .resources. 


H ereisasample xsetup script: 


#!/bin/sh 


# Xsetup @ - setup script for one workstation 
xcemsdb </usr/X11R6/lib/monitors/alex.@ 


xdm 


xconsole -geometry 480x130-0-@ -notify -verbose -exitOnFail & 


AUTHENTICATION WIDGET 


The authentication widget reads a name/password pair from the keyboard. N early every imaginable parameter can be 
controlled with a resource Resources for this widget should be put into the file named by DisplayManager.DI SPLAY . resources. 
All of these have reasonable default values, so it is not necessary to specify any of them. 
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Login. 
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-width, 

-height, 
Login. 
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xX, 


foreground 
font 


-greeting 


unsecureGreeting 


greetFont 
greetColor 


namePrompt 


passwdPrompt 


promptFont 
promptColor 
fail 


.failFont 


failColor 
failTimeout 


translations 


The geometry of the Login widget is normally computed 
automatically. | f you wish to position it elsavhere, specify each 
of these resources. 


The color used to display the typed-in username. 

The font used to display the typed-in username 

A string which identifies this window. The default is x window 
System. 

W hen X authorization is requested in the configuration file 
for this display and noneisin use, this greeting replaces the 
standard greeting. The default isthis is an unsecure session. 
The font used to display the greeting. 

The color used to display the greeting. 

The string displayed to prompt for a username. xrab strips 
trailing whitespace from resource values, so to add spaces at 
the end of the prompt (usually anice thing), add spaces 
escaped with backslashes. T he default is Login:. 

The string displayed to prompt for a password. T he default is 
Password:. 

The font used to display both prompts. 

Thecolor used to display both prompts. 

A message that is displayed when the authentication fails. The 
default isLogin incorrect. 

The font used to display the failure message 

Thecolor used to display the failure message. 

Thenumber of seconds that the failure message is displayed. 
T he default is 30. 

This specifies the translations used for the login widget. Refer 
to the X Toolkit documentation for a complete discussion on 
translations. T he default translation table is 


Ctr1<Key>H delete-previous-character() \n\ 
Ctrl<Key>D delete-character() \n\ 
Ctrl<Key>B move -backward-character() \n\ 
Ctrl<Key>F move-forward-character() \n\ 
Ctrl<Key>A move-to-begining() \n\ 


Ctr1<Key>E move-to-end() \n\ 
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The actions that are supported by the widget are 


delete-previous-character 
delete-character 

move -backward-character 
move -forward-character 


move -to-begining 
move -to-end 
erase-to-end-of-line 


erase-line 
finish-field 


abort-session 


abort -display 


restart-session 


insert-char 


set-session-argument 


allow-all-access 


STARTUP PROGRAM 


Ctrl<Key>K erase-to-end-of-line() \n\ 
Ctrl<Key>U erase-line() \n\ 

Ctrl<Key>X erase-line() \n\ 

Ctrl<Key>C restart-session() \n\ 
Ctrl<Key>nn abort-session() \n\ 
<Key>BackSpace delete-previous-character() \n\ 
<Key>Delete delete-previous-character() \n\ 
<Key>Return finish-field() \n\ 

<Key> insert-char() \ 


Erases the character before the cursor. 
Erases the character after the cursor. 
M oves the cursor backward. 

M oves the cursor forward. 


(Apologies about the spelling error.) M oves the cursor to the 
beginning of the editable text. 


M oves the cursor to the end of the editable text. 
Erases all text after the cursor. 
Erases the entire text. 


If the cursor isin the name field, proceeds to the password field; 
if the cursor isin the password field, checks the current name / 
password pair. If the name/password pair is valid, xdm starts the 
session. O therwise, the failure message is displayed and the 
user is prompted again. 

Terminates and restarts the server. 

Terminates the server, disabling it. This action is not accessible 
in the default configuration. T here are various reasons to stop 
xdm On a system console, such as when shutting the system 
down, when using xdmshe11, to start another type of server, or 
to generally access the console. Sending xdm a stGHuP will 
restart the display. See the subsection “Controlling XDM.” 
Resets the X server and starts a new session. This can be used 
when the resources have been changed and you want to test 
them or when the screen has been overwritten with system 
messages. 

Inserts the character typed. 

Specifies a single word argument that is passed to the session at 
startup. See the subsection “Session Program.” 

Disables access control in the server. Thiscan be used when 
the .xauthority file cannot be created by xam. Be very careful 
using this; it might be better to disconnect the machine from 
the network before doing this. 


The xstartup file is typically a shell script. It isrun as root and should be very careful about security. This is the place to put 
commands that add entries to /etc/utmp (the sessreg program may be useful here), mount users’ home directories from file 
servers, display the message of the day, or abort the session if logins are not allowed. 


xdm 


In addition to any specified by DisplayManager.exportList, the following environment variables are passed: 


DISPLAY The associated display name 

HOME The initial working directory of the user 

USER Theusername 

PATH The value of DisplayManager.DI SPLAY .systemPath 
SHELL The value of DisplayManager.DI SPLAY .systemShel1 
XAUTHORITY M ay be set to an authority file 


No arguments are passed to the script. xdm waits until this script exits before starting the user session. If the exit value of this 
script isnon-zero, xdm discontinues the session and starts another authentication cycle 


Thesample xstartup file shown here prevents login while the file /etc/nologin exists. T hus, this is not a complete example, 
but simply a demonstration of the available functionality. 


H ereisasample xstartup script: 


#!/bin/sh 
# 
# Xstartup 
# 
# This program is run as root after the user is verified 
# 
if [ -f /etc/nologin ]; then 
xmessage -file /etc/nologin 
exit 1 
fi 
sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 
/usr/X11R6/lib/xdm/GiveConsole 
exit 0 


SESSION PROGRAM 


The Xsession program is the command that is run as the user’s session. It isrun with the permissions of the authorized user. 
In addition to any specified by DisplayManager.exportList, the following environment variables are passed: 


DISPLAY The associated display name 

HOME The initial working directory of the user 

USER Theusername 

PATH The value of DisplayManager.DI SPLAY .userPath 
SHELL The user’s default shel (from getpwnam) 
AUTHORITY M ay be set to a nonstandard authority file 
KRBSCCNAME M ay be set to a K erbevos credentials cache file 


At most installations, Xsession should look in sHome for afile xsession, which contains commands that each user would like 
to use as a session. Xsession should also implement a system default session if no user-specified session exists. See the 
subsection “T ypical U sage.” 


An argument may be passed to this program from the authentication widget using the set-session-argument action. T hiscan 
be used to select different styles of session. O ne good use of this feature is to allow the user to escape from the ordinary 
session when it fails. This allows users to repair thar own .xsession if it fails, without requiring administrative intervention. 
The example following demonstrates this feature. 


This example recognizes the special failsafe mode specified in the translations in the xresources file, to provide an escape 
from the ordinary session. It also requires that the .xsession file be executable so you don’t have to guess what shell it wants 
to use. 
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#!/bin/sh 
# 
# Xsession 
# 
# This is the program that is run as the client 
# for the display manager. 
case $# in 
1) 
case $1 in 
failsafe) 
exec xterm -geometry 80x24-0-0 
3 
esac 
esac 
startup=$HOME/.xsession 
resources=$HOME/.Xresources 
if [ -f "$startup" ]; then 
exec "$startup" 
else 
if [ -f "$resources" ]; then 
xrdb -load "$resources" 
fi 
twm & 
xman -geometry +10-10 & 
exec xterm -geometry 80x24+10+10 -ls 
fi 


The user’s .xsession file might look something like the following example D on’t forget that the file must have execute 
permission. 

#!/bin/csh 

# no -f in the previous line so .cshrc gets run to set $PATH 

twm & 

xrdb -merge "$HOME/.Xresources" 

emacs -geometry +0+50 & 

xbiff -geometry -430+5 & 

xterm -geometry -0+50 -1ls 


RESET PROGRAM 


Symmetrical with xstartup, the Xreset script isrun after the user session has terminated. Run as root, it should contain 
commands that undo the effects of commands in xstartup, removing entries from /etc/utmp or unmounting directories from 
file servers. The environment variables that were passed to xstartup are also passed to xXreset. 

A sample xreset script: 

#!/bin/sh 

# 

# Xreset 

# 

# This program is run as root after the session ends 

# 

sessreg -d -l $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 

/usr/X11R6/1ib/xdm/TakeConsole 

exit 0 


CONTROLLING THE SERVER 


xdm controls local servers using PO SIX signals. stcHup is expected to reset the server, closing all client connections and 
performing other cleanup duties. stcTerm is expected to terminate the server. If these signals do not perform the expected 
actions, the resources DisplayManager.DISPLAY.resetSignal and DisplayManager.DISPLAY.termSignal Can specify alternate 
signals. 


xdm 


To control remote terminals not using XD M CP, xdm searches the window hierarchy on the display and uses the protocol 
request KillClient in an attempt to clean up the terminal for the next session. This may not actually kill all of theclients, as 
only those which have created windows will be noticed. xomcr provides a more sure mechanism; when xdm closes its initial 
connection, the session isover and the terminal is required to closeall other connections. 


CONTROLLING xdm 


xdm responds to two signals: staHup and staTerm. When sent a stGHup, xdm rereads the configuration file the access control file, 
and the servers file. For theservers file it notices if entries have been added or removed. If anew entry has been added, xdm 
starts a session on the associated display. Entries that have been removed are disabled immediately, meaning that any session 
in progress will be terminated without notice and no new session will be started. 

W hen sent a sIGTeRM, xdm terminates all sessions in progress and exits. This can be used when shutting down the system. 

xdm attempts to mark its various subprocesses for ps(1) by editing the command-line argument list in place. Because xam can’t 
allocate additional space for this task, it is useful to start xdm with a reasonably long command line (using the full pathname 
should be enough). Each process which is servicing a display is marked -display. 


OTHER POSSIBILITIES 


You can use xdm to run a single session at atime using the 4.3 init options or other suitable daemon by specifying the server 
on the command line: 


xdm -server ":@ SUN-3/60CG4 local /usr/X11R6/bin/X :0" 
Or you might have a file server and a collection of X terminals. The configuration for thisis identical to that of the preceding 
sample, except the xservers file would look like this: 


extol:0 VISUAL-19 foreign 
exalt:0 NCD-19 foreign 
explode: NCR-TOWERVIEW3000 foreign 


This directs xam to manage sessions on all three of these terminals. See the subsection “C ontrolling xam" for a description of 
using signalsto enable and disable these terminals in amanner reminiscent of init(8). 


LIMITATIONS 


One thing that xdm isn’t very good at doing is coexisting with other window systems. To use multiple window systems on the 
same hardware, you'll probably be more interested in xinit. 





FILES 
<XRoot>/1ib/X11/xdm/xdm-config The default configuration file 
$HOME/.Xauthority User authorization file where xdm stores keys for clients to read 
<XRoot>/1ib/X11/xdm/chooser The default chooser 
<xRoot>/bin/X11/xrdb T he default resource database loader 
<XRoot>/bin/X11/X The default server 
<XRoot>/bin/X11/xterm The default session program and failsafe client 
<XRoot>/1ib/X11/xdm/A<display>-<suffix> The default place for authorization files 
/tmp/K5C<display> Kerberos Credentials cache 


N ote: <xRoot> refers to the root of the X11 install tree 


See Also 
X(1), xinit(1), xauth(1), Xsecurity(1), sessreg(1), Xserver(1) 
X Display M anager Control Protocol 
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AUTHOR 
Keith Packard (MIT X Consortium) 


X Verdon 11 Reease 6 


xdpyinto 


xdpyinfo— Display information utility for X 


SYNOPSIS 


xdpyinfo [-display displ ayname] [-queryExtensions] [-ext extension-name] 


DESCRIPTION 


xdpyinfo iS a utility for displaying information about an X server. It is used to examine the capabilities of a server, the 
predefined values for various parameters used in communicating between clients and the server, and the different types of 
screens and visuals that are available. 


By default, numeric information (opcode, base event, base error) about protocol extensions is not displayed. T his informa- 
tion can beobtained with the -queryextensions option. U se of this option on servers that dynamically load extensions will 
likely cause all possible extensions to be loaded, which can be slow and can consume significant server resources. 


D etailed information about a particular extension is displayed with the-ext extensionName option. If extensionName is all, 
information about all extensions supported by both xdpy- info and the server is displayed. 


ENVIRONMENT 


DISPLAY To get the default host, display number, and screen 


SEE ALSO 


X(1), xwininfo(1), xprop(1), xrdb(1) 


AUTHOR 
Jim Fulton (MIT X Consortium) 
X Version 11 Release 6 


Xf86 Accel 


XF86_Accel— Accelerated X W indow System servers for UNIX on x86 platforms with an S3, M ach8, M ach32, M ach64, 
P9000, AGX, ET 4000/W 32, or 8514/A accelerator board 


SYNOPSIS 


XF86_S3 [:displaynumber] [ option ] ... 
XF86_Mach8 [:displaynumber] [ option ] ... 
XF86_Mach32 [:displaynumber] [ option ] ... 
XF86_Mach64 [:displaynumber] [ option ] ... 
XF86_P9000 [:displaynumber] [ option ] ... 
XF86_AGX [:displaynumber] [ option ] ... 
XF86_W32 [:displaynumber] [ option ] ... 
XF86_8514 [:displaynumber] [ option ] ... 


xf86_ Accel 
DESCRIPTION 


xF86_s3 isan 8-bit PseudoC olor, 16-bit T rueC olor and 24-bit T rueC olor server for S3 graphic accderator boards. N ote 16- 
bit and 24-bit operation is not supported on all S3 accelerator boards. Refer to README.s3 for details of which boards are 
supported at which depths. 


XF86_Machs iSan 8-bit PseudoC olor server for AT! M ach8 graphic accderator boards. 


XF86_Mach32 iS an 8-bit PseudoC olor and 16-bit T rueC olor server for AT! M ach32 graphic accelerator boards. N ote, 16-bit 
operation is not supported on all M ach32 accelerator boards. 


XF86_Maché4 iS an 8-bit PseudoC olor, 16-bit T rueC olor, and 24-bit T rueC olor server for AT! M ach64 graphic accelerator 
boards. N ote 16-bit and 24-bit operation is not supported for all RAM DACs. Refer to README.Mach64 for details of which 
RAM DACsare supported at which depths. 


xF86_P9000 isan 8-bit PseudoC olor, 16-bit T rueC olor, and 24-bit T rueC olor server for W etek Power 9000 (P9000) graphic 
accelerator boards. 


XF86_AGX iS an 8-bit PseudoC olor and 16-bit T rueC olor server for AG X/XGA graphic accelerator boards. 
XF86_w32 isan 8-bit PseudoC olor server for ET 4000/W 32, ET 4000/W 32i, and ET 4000/W 32p graphic accelerator boards. 
XF86_8514 iS an 8-bit PseudoC olor server for 8514/A graphic accelerator boards. 
T hese are derived from the x3ge server provided with X11R5, and from the x8514 server developed by Kevin M artin 
(<martin@cs.unc.edu>). 

CONFIGURATIONS 


The servers support the following chipsets: 


XF86_S3 860911, 860924, 86C801, 860805, 86C805i, 860928, 86C928- P, 
860732 (Trio32), 860764 (Trio64), 86C864, 86C868, 860964, 86C968 

XF86_Mach8 ATI mach, AT] mach32 

XF86_Mach32 ATI Mach32 

XF86_Mach64 ATI mach64 

XF86_P9000 Diamond Viper vis, Diamond Viper pcr, Orchid pgeee, and 
some clones (W eitek P9aee) 

XF86_AGX AGX-010, AGX-014, AGX-015, AGX-016, XGA-1, XGA-2 

XF86_W32 ET4000/W32, ET4000/W32i, ET3000/W32p 

XF86_8514 IBM 8514/a and true clones 


For S3, virtual resolutions up to (approximatd y) 1,152x800 are supported, using (up to) 1M B of display memory (the S3 
uses an internal width of 1,280 except for new revisions of some of the chips, hence 1M B can’t support 1,152x900). Physical 
resolutions up to 1,280x1,024 (1,600x1,280 on some cards) are possible using 2M B or more of display memory. (Virtual 
resolution is dependent solely on the anount of memory installed, with the maximum virtual width being 2,048, and 
maximum virtual height is 4,096.) 


Similar resolutions are supported on the M ach64. Refer to README .Mache4 for configuration details. 


Similar resolutions are supported on the M ach32. For the M ach32, themaximum virtual width is 1,536, and the maximum 
virtual height is 1,280. 


For M ach8, the maximum virtual width is 1,024. 
For 8514, the maximum resolution is 1,024x768. 


For theAGX chips, maximum resolution depends upon the chip revision and amount of available display memory. Refer to 
README. agx for configuration details. 
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For the P9000, the virtual and physical resolutions must be the same With sufficient memory, resolutions up to 
1,280x1,024 are supported. 


All the servers that support 24-bit visuals do so using a 32-bit per pixel configuration where 8 bits in every 32 bits is unused. 
This needs to be taken into account when calculating the maximum virtual display size that can be supported at this depth. 


OPTIONS 
In addition to the normal server options described in the Xserver(1) manual page, these servers accept some more command- 
line switches, as described in the xFrees6(1) man page 
TheM aché4, M ach32, $3, P9000, and AGX servers now support more than 8-bit color. The M ach32 and AGX servers 
support 16-bit T rueC olor and the M ach64, S3, and P9000 servers support 16-and 32-bit T rueC olor. The 32-bit T rueC olor 
mode only uses 24 bits per pixel for color information (giving you 16 million colors). T hese modes may be used by 
specifying the -bpp option as specified in the xFreese(1) man page. 


SETUP 
XFrees6 uses a configuration file called xFsécontig for its initial setup. 


See the xFs6config(4/5) man page for general details. H ere only the parts specific to the xF86_s3, XF86_Mach8, XF86_Mach32, 
XF86_Mach64, XF86_P9000, XF86_AGX, XF86_W32, and XF86_8514 Server's are explained. 


Entries for the Device section in the xFséconfig file include the following: 

Chipset "name" Specifies a chipset so the correct driver can be used. Possible 
chipsets are 
XF86_S3 
$3_generic: (for a standard 10 -driven server) 


Mmio_928: (for amemory-mapped IO -driven server on 
86C 928, 86C 732, 86C 764, 86C 864, 86C 868, 86C 964, and 
86C 968 boards) 


XF86_Mach8, Machs (to force the M ach8 server to run on 
M ach32 boards) 


XF86_Mach32, Mach32 

XF86_Mach64, Mach64 

XF86_P9000 
Vipervlb (for the Diamond Viper VLB) 
Viperpci (for the Diamond Viper PC1) 


Orchidp9eee (for the O rchid P9000 and many 
generic P9000-based boards) 


XF86_AGX 
Agx-016 
Agx-015 
Agx-014 
Agx-010 
Xga-2 
Xga-1 


NOTE 


Only the agx-016, agx-015, agx-014, and xGa-2 have been tested. Refer to the xea and Acx-010 section of README. agx before 
attempting to use the other chipsets. 


xf86_ Accel 617 


XF86 W32 

4000w32 
4000w32i 
4000w32i_rev_b 
4000w32i_rev_c 
4000w32p_rev_a 
4000w32p _rev_b 
4000w32p_rev_c 
4000w32p_rev_d 


momo mm Mm Mm 





XF86_8514 
Tbm8514 

Clocks clock ... For boards with nonprogrammable clock chips, the clocks can 
be specified here (See xF86contfig(4/5)). T he P9000 server now 
no longer requires aclocks line. It will now work the same 
way as other servers with a programmable clock chip (that is, 
use the clocks as specified in the M odes). N ote, clocks over 
110 MHz arenot recommended or supported by the P9000 
server. The M ach64 server also does not require a clocks line 
because the clocks arenormally read directly from the video 
card's BIOS. For theM ach64 server, the clocks given in the 
xF86Conf ig file are ignored unless theno_bios_ clocks option is 
given (see below). 

ClockChip "clockchip-type" For boards with programmable clock chips (except with the 
P9000 and AGX servers), the name of the clock chip is given. 
Possible values for the S3 server include "ica2061a", 
“ics9161a", "dcs2834", "sc11412", "s3gendac", "s3 sdac", 
"ti3025", "ti3026", "ics2595", "ics5300", "ics5342", "ch8391", 
"stg1703", aNd "ibm_rgb5xx". 

Ramdac “ramdac-type" This specifies the type of RAM DAC used on the board. O nly 
theS3, AGX, and W 32 servers use this. 

Normal— (S3, AGX) Card does not have one of the other 

RAM DACsmentioned here. This option is only required for 
the S3 server if the server incorrectly detects one of those othe 
RAM DACs. TheAGxX server does not yet auto-detect 

RAM DACs, thisis the default if no RAM DAC is specified. 
Generic— (W 32) This forces the W 32 server to treat the 
RAMDAC asageneric VGA RAMDAC. 

Att20c490— (S3, AGX) Card hasan AT&T 20C 490 or AT&T 
20C 491 RAM DAC. When thedac_8 bit option is specified, 
these RAM D ACs may be operated in 8-bit per RGB mode. It 
also allows 16bpp operation with 801/805/928 boards. T rue 
AT&T 20C 490 RAM DACs should be autodetected by the $3 
server. ThisRAMDAC must be specified explicitly in other 
cases. N ote that 8-bit per RGB mode does not appear to work 
with the Winbond 82C 490 RAM DACs (which SuperProbe 
identifies as AT & T 20C 492). 16bpp works fine with the 
Winbond 82C 490. The Diamond SS2410 RAM DAC is 
reported to be compatible when operating in 15bpp mode 
(not 16bpp). The Chrontel 8391 appears to be compatible in 
all modes. 
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$c15025— (S3, AGX) Card hasa Sierra SC 15025 or SC 15026 
RAM DAC. TheS3 server has code to autodetect this 
RAMDAC. 

$c11482— (S3) Card has a Sierra SC 11482, SC 11483, or 

SC 11484 RAM DAC. TheS3 server has codeto autodetect 
thisRAM DAC. 

$c11485— (S3) Card has a Sierra SC 11485, SC 11487 or 

SC 11489 RAM DAC. TheS3 sever will detect these 

RAM DACsasan sc11482, so this option must be specified to 
take advantage of extra features (they support 16bpp, 15bpp, 
and 8bpp, while the others only support 15bpp and 8bpp). 
Bt485— (s3) Card has a BrookT ree Bt485 or Bt9485 

RAM DAC. This must be specified if the server fails to detect it. 
Att20c505— (S3) Card hasan AT&T 20C505 RAMDAC. 
This must be specified eather if the server fails to detect the 
20C 505, or if the card has a Bt485 RAM DAC and theeare 
problems using clocks higher than 67.5M Hz. 

Att20c498— (S3) Card hasan AT&T 20C 498 or 21C 498 
RAM DAC. This must be specified if the server fails to detect it. 
Att22c498— (S3) Card hasan AT&T 22C498 RAMDAC. 
This must be specified if the server fails to detect it. 
Ibm_rgb514— (S3) Card hasan IBM RGB514 RAM DAC. This 
must be specified if the server fails to detect it. 
Tbm_rgb524— (S3) Card hasan IBM RGB524 RAM DAC. This 
must be specified if the server fails to detect it. 

Ibm_rgb525— ($3) Card hasan IBM regs2s RAM DAC. This 
must be specified if the server fails to detect it. 
Tbm_rgb528— (S3) Card hasan IBM RGB528 RAM DAC. This 
must be specified if the server fails to detect it. 

Stg1700— ($3) Card has an STG1700 RAMDAC. T hiSmust be 
specified if the server fails to detect it. 

Stg1703— ($3) Card has an STG1703 RAMDAC. T hismust be 
specified if the server fails to detect it. 

s3gendac— ($3) Card has an $3 86C 708 GEN DAC. This 
RAM DAC doesnot support 8-bit per RGB mode (don’t 
specify the dac_8_bit option). It allows 16bpp operation with 
801/805 boards. There is currently no autodetection for this 
RAMDAC. 

$3_sdac— (S3) Card has an $3 86C716 SDAC RAMDAC. 
This must be specified if the server fails to detect it. 

1cs5300— ($3) Card has an 1C $5300 RAM DAC. This must be 
specified if the server fails to detect it (the server will recognize 
thisas an S3 GEN DAC which isOK). 

1cs5342— ($3) Card has an 1CS5342 RAM DAC. This must be 
specified if the server fails to detect it (the server will recognize 
thisas an S3 SDAC whichisOK). 

7i3020— ($3) Card hasaT! ViewPoint Ti3020 RAM DAC. 
This must be specified if the server fails to detect the Ti3020. 
N ote that pixa multiplexing will be used for this RAM DAC if 
any mode requires a dot clock higher than 70M Hz. 
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7i3025— (S3) Card hasaT! ViewPoint Ti3025 RAM DAC. 
This must be specified if the server fails to detect the Ti3025. 
7i3026— (S3) Card hasaT! ViewPoint Ti3026 RAM DAC. 
This must be specified if the server fails to detect the Ti3026. 
Bt481— (AGX) Card has a BrookT ree Bt481 RAMDAC. 
Bt482— (AGX) Card has a BrookT ree Bt482 RAMDAC. 
Herc_dual_dac— (AGX) Card (H ercules Graphite Pro) has 
both the 84-pin (Bt485 or AT & T20C 505) and 44-pin (Bt481 
or Bt482) RAM DACsinstalled. 

Herc_small_dac— (AGX) Card (H ercules Graphite Pro) has 
only the 44-pin (Bt481 or Bt482) RAM DAC installed. 

10Base ioaddress Specifies the base address for extended 10 registers. Thisis 
only used by the AGX server, and by the P9000 server for the 
Viper PCI. For details of how to useit, refer to README. agx and 
README . P9000. 

MemBase memaddress Specifies the hard-wired part of the linear framebuffer base 
address. T his option is only used by the P9000, S3, M ach64, 
and M ach32 servers (and only when using a linear 
framebuffer). For the S3 server, the hard-wired part is the high 
10 bits of the 32-bit address (that is, memaddress ismasked with 
oxFFC00000). N ote: This should not be required for the 864 
and 964 chips where the entire framebuffer address is software 
selectable Also, note that in versions prior to 3.1.1, the S3 
server used only the top 6 bits of memaddress, and ored it with 
@x3c00000. T o get the same behavior, or ox3ce0000 with the 
value given previously. For the M ach32 server, the mask is 
oxF8ee000e (except for PC! cards, where the membase setting is 
ignored). 

This option must be specified with the P9000 server. With 
local bus Diamond Vipers the value of memaddress can be 
either 0x80000000, 0x20000000, OF oxAoaae000. T he default is 
@x80000000. Any value should work as long as it does not 
conflict with another device already at that address. For the 
Viper PCI, refer to README. P9000. For the Orchid P9000, the 
base address may be oxceae0000, 0xDe000000, Or exE0000000, 
and must correspond the board's jumper setting. N ote Thes3 
server will normally probe for this address automatically. 
Setting this option overrides that probe. This is not normally 
recommended because the failure of the server's probe usually 
indicates problems in using the linear framebuffer. 


NOTE 


TheM ach64 server requires the menory aperture For !SA bus video cards, this means that the aperture must be enabled 
and the aperture address must beset to a valueless than 16M B (which means that, on ISA systensonly, to usetheM ach64 
server you must have 12M B of main memory or less). N ormally the M ach64 server will use predefined values for this 
address, but setting this option will override the predefined address. 


TheM ach32 server should not require the use of this option under normal circumstances. 
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COPBase baseaddress 
Instance instance 


S3MC1k memc! k 


S3MNAdjust M N 


S3RefClk ref clk 


This sets the coprocessor base address for the AGX serve. 
Refer to README. agx for details. 

This sets the XGA instancenumber for the AG X server. Refer 
to README. agx for details. 

This allows the video card’s memory clock value to be 
specified. Thisis only used for 805i, 864 and T rio32/64 cards, 
and the value should not normally be given here for cards with 
an S3 Gendac or T rio64. This entry doesn’t change the card’s 
memory clock, but it is used to calculate the DRAM timing 
parameters. For further details refer to README.S3. 

This allows some memory timing parameters to be adjusted 
for DRAM cards. For further details refer to README. $3. 

This allows the PLL reference clock to be specified. T his may 
be required for some cards that use the IBM RGB5xx 

RAM DACs. The valueisin M Hz. For further details refer to 
README .$3. 


O ption flags may be specified in either the Device section or the Display subsection of the xFseconfig file 


Option “optionstring” 


Allows the user to select certain options provided by the 
drivers. Currently the following strings are recognized: 
Nomemaccess— ($3) D isable direct access to video memory. 
This option is ignored for the 864 and 964 chips. 

Noaccel— (AGX, P9000) Disable hardware acceleration for the 
P9000, and disables the font cache with the AGX. 
Vram_128—(AGX, P9000) When memory probe fails, use if 
you have 128K x8 VRAM s. 

Vram_256— (AGX, P9000) When memory probe fails, use if 
you don’t have 128K x8 VRAMs. 

Nolinear— (S3 and M ach32) Disable use of a linear- mapped 
framebuffer. 

Ti3020_curs— (S3) Enables the Ti3020’s internal H W cursor. 
(D efault) 

No_ti3020_curs— (S3) Disables the Ti3020’s internal H W 
cursor. 

sw_cursor— ($3, M ach32, M ach64, P9000, AGX) Disable the 
hardware cursor. 

Dac_8 bit— (S3, M ach32, M ach64, AGX) Enables 8-bit per 
RGB. Currently only supported with the Ti3020/5/6, Bt485, 
AT&T20C505, AT&T20C490/1, Sierra $C15025/6, AT&T20C498 and 
$TG1700/3, IBM RGB5xx (S3 server), Bt481 and Bt482 (AGX 
server), AT168875/TLC34075/Bt885 (M ach32 server), ATI68875, 
TLC34075, ATI68860, ATI68880, STG1702, and sTG1703 (M ach64 
server) RAM DACs. Thisisnow set by default in the s3 server 
when one of the preceding RAM D ACs other than the 
AT&T20C490/1 iS used. 

Dac_6 bit— (S3) Force 6-bit per RGB in cases where 8-bit 
mode would automatically be enabled. 

Sync_on_green— (S3, P9000) Enables generation of sync on the 
green signal on cards with Bt485, aTaT20c505, Ti3020/5/6 Or 
rBmrGB5xx RAM DACs. Note Although these RAM DACs 
support sync_on_green, it won't work on many cards because 
of the way they are designed. 
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Power_saver— (S3 and M ach64) This option enables the server 
to use the power-saving features of VESA DPM S-compatible 
monitors. T he suspend level is currently only supported for the 
M aché4 and for the 732, 764, 864, 868, 964, 968 S3 chips. Refer 
to the xFséconfig(4/5) manual page for details of how to set 
the time-outs for the different leve's of operation. This option 
is experimental. 

intel_gx— (M ach32) Sets the hard-wired offset for the linear 
framebuffer correctly for the Inte GX Pro cards. This option 
is equivalent to setting the membase to ox78000000. 
spea_mercury— (S3) Enables pixd multiplex support for SPEA 
Mercury cards (928 +Bt485 RAM D AC). For these cards, pixel 
multiplexing is required in order to use dot clocks higher than 
67.5 MHz and to access more than 1M B of video memory. 
Pixa multiplexing is currently supported only for 
noninterlaced modes, and modes with a physical width no 
smaller than 1,024. 

stb_pegasus— (S3) Enables pixel multiplex support for STB 
Pegasus cards (928 +Bt485 RAM DAC). For these cards, pixel 
multiplexing is required in order to use dot clocks higher than 
67.5 MHz. Pixel multiplexing is currently supported only for 
noninterlaced modes, and modes with a physical width no 
smaller than 1,024. 

number_nine— (S3) Enables pixel multiplex support for 
Number N ineG Xe level 10, 11, 12 cards (928 +Bt485 

RAM DAC). For these cards, pixel multiplexing is required in 
order to use dot clocks higher than 85M Hz. Pix multiplexing 
is currently supported only for noninterlaced modes, and 
modes with a physical width no smaller than 800. This option 
is also required for some other N umber N inecards (for 
example, GxE64 and Gxe64pro). 

diamond— (S3) This option may berequired for some 
Diamond cards (in particular, the 964/968 VRAM cards). 
elsa_w1000pro— (s3) Enables support for the ELSA Winner 
1000 PRO. This option is not usually required because the 
board can be autodetected. 

elsa_w1000isa— (S3) Enables support for the ELSA Winner 
1000 ISA. T his option is not usually required because the 
board can be autodetected. 

elsa_w2000pro— (s3) Enables support for the ELSA Winner 
2000 PRO. This option is not usually required because the 
board can be autodetected. 

pci_hack— (s3) Enables a workaround for problems seen with 
some PCI 928 cards on machines with a buggy SMC UART. 
s3_964_bt485_vclk— (S3) Enables a workaround for possible 
problems on cards using the 964 and Bt48s. 

genoa, stb, hercules, Of number_nine,— (S3) These options may 
be used to select different defaults for the blank dday settings 
for untested cards with IBM RGB5xx RAM D ACsto avoid 
pixd-wrapping problems. 
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slow_vram— (3) Adjusts theVRAM timings for cards using 
slow VRAM. Thisis required for some Diamond Stealth 64 
VRAM and H erculesT erminator 64 cards. 

Fast_vram— (s3) Adjusts the VRAM timings for faste VRAM 
access. There will be display errors and pixd garbage if your 
card can’t support it. 

Slow_dram_refresh— (S3) Adjusts the DRAM refresh for cards 
with Sow DRAM to avoid lines of corrupted pixels when 
switching modes. 

No_block_write— (Maché64) D isables the block write mode on 
cetain types of VRAM M achéé4 cards. If noise or shadows 
appear on the screen, this option should renovethem. 
Block_write— (M ach64) Enables the block write mode on 
cetain types of VRAM M achéé4 cards. N ormally the M ach64 
server will automatically determine if the card can handle 
block write mode, but this option will override the probe 
result. 

No_bios_clocks— (M ach64) The M ach64 server normally 
reads the clocks from the bios. T his option overrides the bios 
clocks and forces the server to use the clocks given in the 
xF86Config file 

There are also numerous tuning options for the AG X server. 
Refer to README. agx for details. 


N ote that xFreese has some internal capabilities to determine what hardware it is running on. Thus, normally the keywords 
chipset, clocks, and videoram don’t have to be specified. But there may be occasions when this autodetection mechanism 
fails, (for example, too high aload on the machine when you start the server). For cases like this, one should first run the 
server on an unloaded machine look at the results of the autodetection (that are printed out during server startup), and then 
explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock values, be 


specified in the xFséconfig file. 


FILES 


<XRoot>/bin/XF86 S3 
<Root>/bin/XF86 Mach8 
<XRoot>/bin/XF86 Mach32 
<XRoot>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<XRoot>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Config 
<Root>/1ib/X11/XF86Config 
<XRoot>/1ib/X11/doc/README .agx 
<XRoot>/1lib/X11/doc/README .P9000 
<Root>/1ib/X11/doc/README.S3 
<XRoot>/1lib/X11/doc/README .W32 


N ote: <xRoot> refers to the root of the X11 install tree. 


The8-, 16-, and 24-bit color X server for $3 
The8-bit color X server for M ach8 

The8- and 16-bit color X server for M ach32 
The8-, 16-, and 24-bit color X server for M ach64 
The8-, 16-, and 24-bit color X server for the P9000 
The8- and 16-bit color X server for AGX and XGA 
The8-bit color X server for ET 4000/W 32 

The 8-bit color X server for IBM 8514 and true compatibles 
Server configuration file 

Server configuration file (secondary location) 

Extra documentation for the AG X server 

Extra documentation for the P9000 server 

Extra documentation for the S3 server 

Extra documentation for the W 32 server 
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SEE ALSO 


x(1), Xserver(1), xFrees86(1), xF86Config(4/5), xvidtune(1), xdm(1), xf8écontig(1), xinit(1) 


AUTHORS 


In addition to the authors of xFreese the following people contributed major work to this server: Kevin M artin 
(martin@cs.unc.edu), ]on Tombs (tombs@xFree86.org), Rik Faith (faith@cs.unc. edu). (Did the overall work on the base 
accelerated servers.) 


D avid D awes (dawes@xFree86.org), Dirk H ohndel (hohndelexFree86.org), D avid W exdblat (dwexexFree86.org). (M erged 
their work into xFree86.) 


Jon Tombs (tombsexFree86.org), D avid W exeblat (dwexexFrees86.org), D avid D awes (dawes@xFree86.org), Amancio H asty 
(hasty@netcom. com), Robin Cutshaw (robin@xFree86.org), N orbert D istler (Norbert .Distler@physik.tu-muenchen.de), Leonard 
N. Zubkoff (1nze@dandelion.com), H arald K oenig (koenig@tat .physik.uni-tuebingen.de), Bernhard Bender 
(br@elsa.mhs.compuserve.com), H ans N asten (nasten@everyware.se). (D evelopment and improvement of the s3-specific code.) 





Kevin Martin (martin@cs.unc.edu), Rik Faith (faith@cs.unc. edu), Tiago Gons (tiago@comosjn.hobby.n1), H ans N asten 
(nasten@everyware.se), SCott Laird (1air@midway.uchicago.edu). (D evdopment and improvenent of the machs- and 8514/A- 
specific code.) 

Kevin M artin (martin@cs.unc.edu), Rik Faith (faith@cs.unc.edu), Mike Bernson (mike@mbsun.mlb.org), M ark W eaver 
(MarkWeaver@brown.edu), Craig Groeschel (craig@metrolink.com). (D evelopment and improvement of the mach32-specific code 


Kevin Martin, (martin@cs.unc.edu). (D evdopment of the mache4-specific code.) 


Erik N ygren (nygren@mit.edu), H arry Langenbacher (harry@brain. jpl.nasa.gov), Chris M ason 
(clmtch@osfmail.isc.rit.edu), H enrik H armsen (harmsen@eritel.se). (D evelopment and improvement of the pgaee-specific 
code) 

Henry Worth (henry.worth@amail.amdahl.com). (D evdopment of the acx specific code.) 

Glenn Lai (glenn@cs.utexas.edu). (D evelopment of the ET4000/w32-specific code.) 


See also the xFree86(1) manual page. 


BUGS 
Some $3 cards with Bt485 RAM DACsare currently restricted to dot-clocks less than 85M Hz. 


The P9000 server may still have problems with cards other than the Diamond Viper VLB. There may still be problems with 
VGA mode restoration, but these should almost never occur. U sing physical resolutions different from the virtual resolution 
is not supported and is not possible with the P9000. U se at dot-clocks greater than 110M H zis not recommended and not 
supported. Diamond claims that 135M Hz isthe maximum clock speed, but some of its bt4gss are not rated that high. If you 
do not havea 135M H zbt4gs5 on your Viper, contact Diamond tech support and they will send you an RM A number to 
replace the board. Acceleration is bang added in slowly. At the present, only copyArea, MoveWindow, and DrawLine are 
implemented. O ther accelerated features are being tested and may be available in the next rdease. There seems to bea 
problem with olvwm when used with xam and vt switching. T he cursor will be messed up when you return to avt if the cursor 
changed while you were in the vr. 


CONTACT INFO 
XFree86 source is available from the FT P server ftp. xFree86.Org and mirrors. Send e-mail to xFrees6exFrees6.Org for details. 
xFreese Vergon 3.1.2 
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XF86_ Mono 


XF86_Mono— 1-bit nonaccderated X Window System servers for UN IX on x86 platforms 


SYNOPSIS 


XF86 Mono [:displaynumber] [ option ] ... 


DESCRIPTION 


XF86_Mono iS a 1-bit StaticG rey server for VGA and Super VGA cards and for some othe: monochrome cards. 


CONFIGURATIONS 


T he xF86_Mono server supports the following popular Super VGA chipsets in monochrome mode 


ATI 


Tseng 

W estern D igital 
Genoa 

Trident 

NCR 

Compaq 

Oak 

Cirrus 


18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3 
68800 -6, 688Q0AX, 688Q0LX, 88800CX, 88800GX 


ET3000, ET4000, ET4000/W32 

PVGA1, WD90C00, WD90C10, WD90C11, WD90C30, WD90C31, WD90C33 
GVGA 

TVGA8800CS, TVGA8900B, TVGA8900C, TVGAB900CL, TVGA9000 
77022, 77C22E 

AVGA 

OTI067, OTI077, OTI087 


CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, CLGD5429 
CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, CLGD6225 
CLGD6235, CL6410, CL6412, CL6420, CL6440 


The xF86_Mono server supports the following monochrome cards and resolutions: 


Sigma 
H yundai 
Apollo 


H ercules and compatibles cards 


L-View, LaserView PLUS (in lbpp mode): 1,664x1,280 
H GC-1280: 1,280[1,472]x1,024 


Monochrome card (with 1D 9) from Apollo workstations: 
1,280x1,024 


720x348 


Additionally, it supports generic VGA cards with a maximum virtual resolution of (approximatdy) 800x650. 


On supported SVGA chipsets, xF86_Mono will use up to 1/4 of display memory, which yidds a maximum virtual resolution of 
(approximate y) 1,664x1,260 with 1M B of display memory. xF86_Mono does not support the accderated functions of the 


supported chipsets. 
OPTIONS 


In addition to the normal server options described in the Xserver(1) manual page, xF86_Mono accepts some more command- 


line switches, as described in the xFrees6(1) man page 


SETUP 


XFree86 uses a configuration file called xF8écontig for its initial setup. 


See the xFseconfig(4/5) man page for general details. H ere only the xF86_Mono specific parts are explained. 


The driver entry in Screen section of the xF86contig file should be set to vga2 for VGA and SVGA boards, and mono for non- 
VGA mono boards. If screen sections are present for both of these, the server will start in a dual-headed configuration. 
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Entries for the Device section in the xFséconfig file include the following: 


chipset "name" Specifies a chipset so the correct driver can be used. Possible 

chipsets for VGA2: 

ATI Vgawonder 

Tseng Et3000, et4000, et4000w32, et4000w32i, 
et4000w32p 

Western D igital Pvgat, wd9@c00, wd90c10, wd90c30, 
wd90c31, wd90c33 

Genoa Gvga 

Trident Tvga8800cs, tvga8900b, tvga8900c, 
tvga8900c1, tvga9000 

NCR Ncr77c22, ncr77c22e Compaq: cpq avga 
OAK: oti067, oti077, oti087 

Cirrus C1gd5420, clgd5422, clgd5424, clgd5426, 


clgd5428, clgd5429, clgd5430, clgd5434, 
c1gd5436, clgd6205, clgd6215, clgd6225, 
clgd6235, cl16410, c16412, cl6420, cl6440 


Generic VGA generic 
Possible chipsets for mono: 
H yundai hgc1280 
Sigma sigmalview 
Apollo apollo9 
H ercules hercules 
MemBase memaddress Specifies the base address of the video memory. This option is 


only used for the Sigma LaserViewcards. Valid addresses for 
these cards are 0xA0000, @xB0000, 0xC0000, 0xD0000, OxE0000. The 
default is oxEoo000. 


Black red green blue Sets the black color to the RGB values specified. T hese values 
must be given as integers in the range 0-63. The default iso o 
e. This option is only valid for the vga2 screen type. 

White red green blue Sets the white color to the RGB values specified. T hese values 
must be given as integers in the range 0-63. T he default is 63 
63 63. T his option is only valid for the vga2 screen type 

Option “optionstring” Allows the user to select certain options provided by the 
drivers. Currently the following strings are recognized: 
legend— For Sigma Legend ET 4000-based boards. T his 
option enables a special clock-selection algorithm used on 
Legend boards, and M UST be specified for these boards to 
function correctly. 
swap_hibit— For Western Digital/PVGA1 chipsets. Some 
W estern D igital-based boards require the high-order clock- 
select lead to be inverted. It is not possible for the server to 
determine this information at run-time If the 9th clock in the 
list of clocks detected by the server is less than 30M hz, this 
option likely needs to be set. 
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Hibit_low, hibit_high— For Tseng ET 4000 chipsets. With 
some ET 4000 cards, the server has difficulty getting the state 
of the high-order clocks select bit right when started from a 
high-resolution text mode. T hese options allow the correct 
initial state of that bit to be specified. To find out what the 
correct initial state is, start the server from an 80x25 text 
mode This option is only needed if the clocks reported by the 
server when started from a high-resolution text mode differ 
from those reported when it is started from an 80x25 text 
mode 
8clocks— For the PVGAI chipset, the default is 4 clocks. 
Some cards with this chipset may support 8 clocks. Specifying 
this option will allow the driver to detect and use the extra 
clocks. 
16clocks— For T rident Tvaasgees and sgeec chipsets. Some 
newer boards using sge0s and sgeec chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boards will 
have a TCK9@02 or TcK9004 Chip on them. Specifying this option 
will allow the driver to detect and use the extra 8 clocks. 
Power_saver— | his option enables the server to use the power 
saving features of VESA D PM S-compatible monitors. T he 
suspend level is currently not supported. Refer to the 
xF86Config(4/5) manual page for details of how to set the time 
outs for the different levels of operation. This option is 
experimental. 
secondary— For the hgc1280 and apollog chipsets. T his option 
allows the use of these cards jumpered to the secondary 1/0/ 
memory address, T hese addresses are 
hgc1280: 1/0 @x3BQ-@x3BF, mem @xBQ000-OxBFFFF (prim.) 

1/0 x390-0x39F, mem @xC8000-OxCFFFF (SEC.) 
apollo9: 1/0 0x3B0-Ox3BF, mem OxFAQQ00-OxFDFFFF (prim.) 

1/0 @x3D0-0x3DF, mem @xA0000-OxDFFFF (SEC.) 
XFree86 Can detect the ec -1280 on both primary and 
secondary address; for the apollo card the primary address is 
used by default. 


N ote that xFreese has some internal capabilities to determine what hardware it is running on. T hus, normally the keywords 
chipset, clocks, and videoram don’t have to be specified. But there may be occasions when this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this, one should first run 
XF86_Mono on an unloaded machine, look at the results of the autodetection (that are printed out during server startup) and 
then explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock 


values, be specified in the xFséconfig file 


FILES 


<XRoot>/bin/XF86 Mono 


/etc/XF86Conf ig 
<XRoot>/lib/X11/XF86Config 


N ote: <xRoot refers to the root of the X11 install tree 


The monochrome X server for VGA, SVGA and other 
monochrome cards 


Server configuration file 
Server configuration file 
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SEE ALSO 


x(1), Xserver(1), xFrees86(1), XxF86Config(4/5), xf8écontig(1), xvidtune(1), xdm(1), xinit(1) 


BUGS 


There areno known bugs at thistime, although we wdcome reports e-mailed to the address listed below. 


CONTACT INFO 
XFree86 Source is available from the FT P server ftp.xFree86.org. 
Send e-mail to xFrees6exFree86.org for details. 


AUTHORS 
Refer to the xFreese(1) manual page. 
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xFg6_svGA— N onaccelerated SVGA X Window System servers for UNIX on x86 platforms 


SYNOPSIS 


XF86 SVGA [:displaynumber] [ option ] ... 


DESCRIPTION 


XF86_SVGA iS an 8-bit PseudoColor, 16-bit T rueC olor and 24-bit T rueC olor server for Super VGA cards. It is derived from 
the x3se server provided with x11R5. N ote: 16-bit T rueC olor is currently only supported for some Cirrus and ARK chips, and 
24-bit T rueC olor is only supported for some Cirrus chips. 


CONFIGURATIONS 


The xF86_svea server supports the following popular Super VGA chipsets in 256-color mode Virtual resolutions up to 
(approximate y) 1152x900 are supported, using (up to) 1M B of display memory. T he Western D igital wogec33 and some of 
the Cirrus chipsets support up to 2M B of display memory and virtual resolutions of 1,280x1,024 and higher. Some of the 
Cirrus chipsets also support 16bpp and 32bpp (truecolor) modes on certain configurations. Some of the ARK chipsets 
support 16bpp modes on certain configurations. Generic VGA cardsare also supported at 8bpp 320x200 only. 


ATI 18800, 18800-1, 28800-2, 28800 -4, 28800-5, 28800-6, 68800-3, 
68800-6, 68800AX, 68800LX, 88800CX, 88800GX 

Tseng ET3000, ET4000, ET4000/W32 

W estern D igital PVGA1, WD9@C00, WD90C10, WD90C11, WD90C24A, WD9@C30, WD90C31, 
WwD9ec33 

Genoa GVGA 

Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

NCR 77022, 77C22E 

Cirrus Logic CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, 


CLGD5429,CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, 
CLGD6225, CLGD6235, CL6410, CL6412, CL6420, CL6440 


ARK ARK10Q0PV, ARK10@0VL, ARK2000PV 
RealT ek RTG3106 
Compaq AVGA 


Oak OTI067, OTI077, OT1087 
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Avance Logic 
Chips & Technology 
MX 

Video7 


AL2101, ALT2301, ALI2302, ALI2308, ALI2401 


65520, 65530, 65540, 65545 


MX68000, MX68010 
HT216-32 


Accelerated support is included for most of the Cirrus chipsets, and for the Western Digital wo9ec31 and wogec3s chipsets. 
Accelerated support for the ET4000/w32 is implemented in a separate server (see xF86_w32(1)). Users of boards based on ATI's 
M ach8, M ach32, and M ach64 chipsets should refer to the xF86_machs(1), xF86_Mach32(1) and xF86_Mach64(1) manual pages, 


respectively. 


OPTIONS 


In addition to the normal server options described in the xserver(1) manual page, xF86_svGa accepts some more command- 


line switches, as described in the xFrees6(1) man page 


SETUP 


XFree86 uses a configuration file called xF8écontig for its initial setup. 


See the xFseconfig(4/5) man page for general details. H ere only the xFg6_svaa specific parts are explained. 


This server requires a Screen section in the xFs6contig file with the Driver entry set to svga. 


Entries for the Device section in the xFséconfig file include 


chipset "name" 


Specifies a chipset so the correct driver can be used. Possible 


chipsets are 
ATI 
Tseng 


W estern D igital 


Genoa 
Trident 


NCR 
Cirrus Logic 


RealT ek 
ARK 
Compaq 
Oak 

Avance Logic 


Chips & Technology 
MX 

Video7 

Generic 


vgawonder 


et3000, et4000, et4000w32, 
et4000w32i, et4000w32p 


pvga1, wd90c00, wd90c10, wd90c24 
wd90c30, wd90c31, wd90c33 

gvga 

tvga8800cs, tvga8900b, tvga8900c, 
tvga8900c1, tvga9000 


ner77c22, ncr77c22e 


clgd5420, clgd5422, clgd5424 
clgd5426, clgd5428, clgd5429, 
c1gd5430, clgd5434, clgd5436 
clgd6205, clgd6215, clgd6225, 
clgd6235, cl16410, cl6412, cl6420, 
c16440 


realtek 

ark1000pv, ark1000vl, ark2000pv 
cpgq_avga 

oti67, 0ti077, 0ti087 


a12101, ali2301, ali2302, ali2308, 
ali2401 


ct65520, ct65530, ct65540, ct65545 
mx 
video7 


generic 
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Option “optionstring” Allows the user to select certain options provided by the 
drivers. Currently the following strings are recognized: 
legend— For Sigma Legend &14000-based boards. T his option 
enables a special clock-selection algorithm used on Legend 
boards, and M UST be specified for these boards to function 
correctly. 
swap_hibit— For Western D igital/PVGA1 chipsets. Some 
W estern D igital-based boards require the high-order clock- 
select lead to be inverted. It is not possible for the server to 
determine this information at run-time If the 9th clock in the 
list of clocks detected by the server is less than 30M hz, this 
option likely needs to be set. 

Hibit_low, hibit_high— For Tseng ET4000 chipsets. W ith some 
ET4000 cards, the server has difficulty getting the state of the 
high-order clocks select bit right when started from a high- 
resolution text mode. T hese options allow the correct initial 
state of that bit to be specified. To find out what the correct 
initial state is, start the server from an 80x25 text mode This 
option is only needed if the clocks reported by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 
8clocks— For the PVGAI chipset, the default is 4 clocks. 
Some cards with this chipset may support 8 clocks. Specifying 
this option will allow the driver to detect and use the extra 
clocks. 

16clocks— For T rident Tveasgees and sgeec chipsets. Some 
newer boards using sga0s and sgeec chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boards will 
have a TCk9ee2 or Tck9004 chip on them. Specifying this option 
will allow the driver to detect and use the extra 8 clocks. 
probe_clocks— For Cirrus chipsets. T he Cirrus driver has a 
fixed set of clocks that are normally used. Specifying this 
option will force the driver to probe for clocks instead of 
reporting the built-in defaults. This option is for debugging 
purposes only. 

power_saver— T his option enables the server to use the power- 
saving features of VESA D PM S-compatible monitors. T he 
suspend level is currently not supported. Refer to the 
xF86Config(4/5) manual page for details of how to set the time 
outs for the different levels of operation. This option is 
experimental. 

noaccel— For Cirrus and W D chipsets. This option disables 
the accelerated features for the c1gd5426, clgd5428, wd90c24, 
wd90c31, and wdgac33 chipsets. 

fifo_conservative— For Cirrus chipsets. T his option sets the 
crt_FiFo threshold to a conservative value for dot clocks above 
65M Hz. This reduces performance, but may help in 
eliminating problems with “streaks” on the screen during 
BitBLT Operations. 

fifo_aggressive— For Cirrus chipsets. This option sets the 
crt_F1Fo threshold to an aggressive value for dot clocks above 
65M Hz. This may increase performance. 
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slow_dram— For Cirrus chipsets. This option sets the D RAM 

timings for sow DRAM chips. 

fast_dram— For ET 4000 and Cirrus chipsets. This option sets 

theD RAM timingsfor fast DRAM chips. 

no_2mb_bankse1l— For Cirrus chipsets. T his option is required 

for Cirrus cards with 2M B of videoram, which isin the form of 

512kx8 DRAM s (4 chips) rather than 256kx4 DRAM s(16 

chips). 

no_bitbit— For Cirrus chipsets. T his option disables use of 

hardware BitBLT. 

linear— Attempt a linear mapping of the framebuffer into 

high memory. Currently only supported for some Cirrus 

configurations. 

med_dram, favour_bitblt, sw cursor, clgd6225 lcd, mmio— M ore 

Cirrus-specific options. Refer to /usr/X11R6/1ib/X11/doc/ 

README.cirrus for a detailed description of Cirrus options. 
speedup "selection" Sets the selection of speedups to use. T he optional selection 

string can take the following values: 

none 

all 

If the selection string is omitted, or if the speedup option is 

omitted, the sdection defaults to a11. Some of the SpeedU ps 

can only be used with the ET4ee0, wogec31, and wogec33 

chipsets and others require a virtual resolution with a xaim of 

1024. SpeedU ps that won’t work with a given configuration 

are automatically disabled. 


nospeedup Disables the SpeedU p code This is equivalent to speedup 
none, 

Ramdac ramdac-type This specifies the type of RAM DAC used on the board. O nly 
the ark driver currently uses this. RAM DAC types recognized 
include 


Att20c490— AT&T 20C 490 or compatible 8-bit RAM DAC. 
Att20c498— AT&T 20C 498 or compatible 16-bit RAM DAC. 
Zoomdac— RAM DAC used by theH ercules Stingray Pro/V and 
64/V. 

stgi700— ST G1700 or compatibleRAM DAC. 


N ote that xFreese has some internal capabilities to determine what hardware it is running on. Thus, normally the keywords 
chipset, clocks, and videoram don’t have to be specified. But there may be occasions when this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this, you should first run 
XF86_SVGA on an unloaded machine, look at the results of the autodetection (that are printed out during server startup), and 
then explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock 
values, be specified in the xFséconfig file 


FILES 
<XRoot>/bin/XF86 SVGA TheSVGA color X server 
/etc/XF86Conf ig Server configuration file 
<XRoot>/1ib/X11/XF86Conf ig Server configuration file 
<XRoot>/1ib/X11/doc/README . ark Extra documentation for the ARK driver 


<XRoot>/1ib/X11/doc/README.ati Extra documentation for the AT! vgawon-der driver 
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<XRoot>/1ib/X11/doc/README.cirrus Extra documentation for the Cirrus driver 
<XRoot>/1ib/X11/doc/README. trident Extra documentation for the T rident driver 
<XRoot>/1ib/X11/doc/README.tseng Extra documentation for the ET4000 and ET3000 drivers 
<XRoot>/1ib/X11/doc/README .Oak Extra documentation for the O ak driver 
<XRoot>/1ib/X11/doc/README .Video7 Extra documentation for the Video7 driver 
<XRoot>/1ib/X11/doc/README .WstDig Extra documentation for the W D/PVGA driver 


N ote: <xRoot> refers to the root of the X11 install tree. 


SEE ALSO 


x(1), Xserver(1), xFrees86(1), XxF86Config(4/5), xf8écontig(1), xvidtune(1), xdm(1), xinit(1) 


BUGS 


Bug reports are welcome, and should be emailed to the address listed below. 


CONTACT INFO 
XFree86 Source is available from the FT P server ftp.xFree86.org. 
Send e-mail to xFrees6exFree86.org for details. 


AUTHORS 
Refer to the xFrees6(1) manual page. 
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XxF86 vGA16— 4-bit nonaccelerated X Window System server for UNIX on x86 platforms 


SYNOPSIS 


XF86 VGA16 [:displaynumber] [ option ] ... 


DESCRIPTION 


XxF86_VGA16 iSa4-bit color server for vea cards. The default root visual for this server isstaticColor. It also includes support 


for the non-VGA monochrome cards described in the xF86_Mono(1) manual page. It may be run in a dual-headed configura- 
tion. 


CONFIGURATIONS 


The xF86_veai6e server supports the following popular svea chipsets in 16-color mode. 


ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 
68800-6, 68800AX, 688Q0LX, 88800CX, 88800GX 

Tseng ET4000 

Trident TVGA8800CS, TVGA8900B, TVGA89@0C, TVGA89@QCL, TVGA9000 

Cirrus CL6410, CL6412, CL6420, CL6440 

Oak OTI067, 0T1077, OT1087 


Additionally, it supports generic VGA cards. 
XF86_VvGA16 does not support the accelerated functions of the supported chipsets. 
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OPTIONS 


In addition to the normal server options described in the xserver(1) manual page, xF86_vGA16 accepts Some more command- 
line switches, as described in the xFrees6(1) man page 


SETUP 


XFreegs6 Uses a Configuration file called xFséconfig for its initial setup. 
See the xFs6config(4/5) man page for general details. H ere, only the xF8e_veate specific parts are explained. 


The driver entry in the screen section of the xF86conf ig file should be set to vgai6.T 0 run in dual-headed configuration, 
there should also bea Screen section with the Driver entry set to mono. 


Entries for the Device section in the xFséconfig file include the following: 


chipset "name" Specifies a chipset so the correct driver can be used. Possible 
chipsets are 
ATI vgawonder 
Tseng et4000, et4000w32, et4000w32i, et4000w32p 
Trident tvga8800cs, tvga8900b, tvga8900c, 
tvga8900c1, tvga9000 
Cirrus 16410, cl16412, cl6420, cl6440 
Oak oti067, oti077, oti087 
GenericVGA generic 
Option “optionstring” Allows the user to select certain options provided by the 


drivers. Currently, the following strings are recognized: 
legend— For Sigma Legend &14e00-based boards. T his option 
enables a special clock-selection algorithm used on Legend 
boards, and M UST be specified for these boards to function 
correctly. 

hibit_low, hibit_high— For Tseng ET4000 chipsets. W ith some 
ET4000 cards, the server has difficulty getting the state of the 
high-order clocks select bit right when started from a high- 
resolution text mode. T hese options allow the correct initial 
state of that bit to be specified. To find out what the correct 
initial state is, start the server from an 80x25 text mode This 
option is only needed if the clocks reoorted by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 
power_saver— T his option enables the server to use the power 
saving features of VESA D PM S-compatible monitors. T he 
suspend level is currently not supported. 

Refer to the xrséconfig(4/5) manual page for details of how to 
set the time-outs for the different levels of operation. This 
option is experimental. 


N ote that xFreese has some internal capabilities to determine what hardware it is running on. T hus normally the keywords 
chipset, clocks, and videoram don’t have to be specified. But there may be occasions when this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this, you should first run xF8e 
veaié on an unloaded machine, look at the results of the autodetection (that are printed out during server startup), and then 
explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock values, be 
specified in the xFséconfig file. 
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FILES 
<XRoot>/bin/XF86 VGA16 The 16-color X server 
/etc/XF86Conf ig Server configuration file 
<XRoot>/1ib/X11/XF86Config Server configuration file 


N ote: <xRoot> refers to the root of the X11 install tree. 


SEE ALSO 


x(1), Xserver(1), xFrees86(1), XxF86Config(4/5), XF86 Mono(1), xf8éconfig(1), xvidtune(1), xdm(1), xinit(1) 


CONTACT INFO 
XFree86 source is available from the FT P server ftp.xFree86.org. 
Send e-mail to xFrees6exFree86.org for details. 


AUTHORS 
The primary developer of this server is Gartjan Akkerman (akkerman@dutiba.twi.tudelft.nl1). 
See also the xFree86(1) manual page. 
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xf86config— Generate an xFsécontig file 


SYNOPSIS 


xf86config 


DESCRIPTION 


xfgéconfig isan interactive program for generating an xF8econfigfile for usewith xFreese X servers. 


FILES 


<xroot>/1ib/X11/Cards Video cards database 


SEE ALSO 


xFree86(1), XxF86Config(4/5), reconfig(1) 


AUTHOR 


H arm H anenaayer 
xFreesé Vargon 3.1.1 
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xfd— Display all the charactersin an X font 


SYNOPSIS 


xfd [-options ...] -fn fontname 
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DESCRIPTION 


The xfa utility creates a window containing the name of the font being displayed, a row of command buttons, several lines of 
text for displaying character metrics, and a grid containing one glyph per cdl. The characters are shown in increasing order 
from left to right, top to bottom. The first character displayed at the top left will be characte: number 0 unless the -start 
option has been supplied, in which case the character with the number given in the-start option will be used. 


The characters are displayed in a grid of boxes, each large enough to hold any single character in the font. Each character 
glyph is drawn using the PolyText16 request (used by the x1ib routine xDrawstring16). If the -box option is given, a rectangle 
will be drawn around each character, showing where an ImageText16 request (used by the x1ib routine xDrawImageString16) 
would cause background color to be displayed. 


The origin of each glyph is normally set so that the character is drawn in the upper left corner of the grid cell. H owever, if a 
glyph has a negative left bearing or an unusually large ascent, descent, or right bearing (as isthe case with cursor font), some 
characters may not appear in ther own grid cells. The-center option may be used to force all glyphs to be centered in thar 
respective cells. 


All the characters in the font may not fit in the window at once To seethe next page of glyphs, press the N ext button at the 
top of the window. To see the previous page, press Prev. To exit xfa, press Q uit. 


Individual character metrics (index, width, bearings, ascent, and descent) can be displayed at the top of the window by 
clicking on the desired character. 


The font name displayed at the top of the window is the full name of the font, as determined by the server. See x1sfonts for 
ways to generate lists of fonts, as well as more detailed summaries of their metrics and properties. 


OPTIONS 
xfd accepts all of the standard toolkit command-line options along with the following additional options: 
-fn font This option specifies the font to be displayed. This can also be 
set with the FontGrid font resource. A font must be specified. 
-box This option indicates that a box should be displayed outlining 


the area that would be filled with background color by an 
ImageText request. This can also be set with the FontGrid 
boxChars resource. T he default isralse. 

-center This option indicates that each glyph should be centered in its 
grid. This can also be set with the FontGrid centerchars 
resource. The default is False. 

-start number This option specifies the glyph index of the upper left corner 
of thegrid. Thisis used to view characters at arbitrary 
locationsin the font. T his can also be set with the FontG rid 
startChar resource The default iso. 





-be color This option specifies the color to be used if ImageText boxes 
are drawn. This can also be set with the FontGrid boxcolor 
resource. 

-rows numr ows This option specifies the number of rows in the grid. T his can 
also be set with the FontGrid ce1lrows resource 

-columns numcol s This option specifies the number of columnsin the grid. T his 





can also be set with the FontG rid cel1columns resource, 


WIDGETS 
In order to specify resources, it is useful to Know the widgets that compose xfd. In the notation below, indentation indicates 
hierarchical structure. The widget class name is given first, followed by the widget instance name. T he application class name 
iS Xfd. 
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Xfd xfd 
Paned pane 
Label fontname 
Box box 
Command quit 
Command prev 
Command next 
Label select 
Label metrics 
Label range 
Label start 
Form form 
FontGrid grid 
FONTGRID RESOURCES 


The FontG rid widget is an application-specific widget, and a subclass of the Simple widget in the Athena widget set. The 
effects and instance names of this widget’s resources are given in the “O ptions” subsection. C apitalize the first letter of the 
resource instance name to get the corresponding class name. 


APPLICATION SPECIFIC RESO URCES 


T he instance names of the application-specific resources are given in the following list. C apitalize the first letter of the 
resource instance name to get the corresponding class name T hese resources are unlikely to be interesting unless you are 
localizing xfd for a different language. 


selectFormat Specifies a printf-style format string used to display informa- 
tion about the sdected character. T he default is character 
Ox%02x%02x (%u,%uU) (%#0,%#0). T he arguments that will come 
after the format string are 


char.byte1, char.byte2, char.byte1, char.byte2, char.byte1, 
char.byte2. char.byte1 iS byte 1 of the selected character. 
char.byte2 is byte 2 of the selected character. 

metricsFormat Specifies a printf-style format string used to display character 
metrics. The default iswidth %d; left %d, right %d; ascent 
%d, descent %d (font %d, %d). T he arguments that will come 
after the format string are the character metrics width, 
lbearing, rbearing, character ascent, character descent, font 
ascent, and font descent. 

rangeFormat Specifies a printf-style format string used to display the range 
of characters currently being displayed. T he default is range: 
Ox%02x%02x (%u,%U) thru Ox%02x%02x (%u,%u). T he arguments 
that will come after the format string are the following fields 
from the xFontstruct that is returned from opening the font: 
min_byte1, min_char_or_byte2, min_byte1, min_char_or_byte2 
max_byte1, max_char_or_byte2, max_byte1, max_char_or_byte2 

startFormat Specifies a printf-style format string used to display informa- 
tion about the character at the upper left corner of the font 
grid. The default is upper left: @x%04x (%d,%d). The 
arguments that will comeafter the format string are the new 
character, the high byte of the new character, and the low byte 
of the new character. 

nocharFormat Specifies a printf-style format string to display when the 
selected character does not exist. The default isno such 
character Ox%02x%02x (%u,%u) (%#0,%#o. T he arguments that 
will come after the format string are the same as for the 
select-Format resource 
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SEE ALSO 

x(1), x1sfonts(1), xrdb(1), xfontse1(1), X Logical Font Description C onventions 
BUGS 

The program should skip over pages full of nonexistent characters. 
AUTHOR 


Jim Fulton (MIT X Consortium); previous program of the same name by M ark Lillibridge (MIT Project Athena) 
X Verson 11 Release 6 
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XFree86-— X11R6 for UNIX on x86 platforms 
DESCRIPTION 


xFrees6 iSa collection of X servers for UNIX-like O Sson Inte x86 platforms. This work is derived from x386n1.2, which was 
contributed to x11R5 by Snitily Graphics Consulting Service 


CONFIGURATIONS 
XFree86 Operates under the following operating systems: 


SVR3.2: SCO 3.2.2, 3.2.4, ISC 3.x, 4.x 

SVR4.0: ESIX, M icroport, Dell, UHC, Consensys, MST, ISC,AT&T,NCR 
SVR4.2: Consensys, U nivel (UNI XW are) 

Solaris (x86) 2.1, 2.4 

FreeBSD 1.1.5, 2.0, 2.0.5, N@BSD 1.0 (i386 port only) 
BSD /386 version 1.1 and BSD/OS 2.0 

M ach (from CMU) 

Linux 

Amoeba version 5.1 

M inix-386vm version 1.6.25.1 

LynxO SAT versions 2.2.1 and 2.3 


NETWORK CONNECTIONS 


XFree86 Supports connections made using the following rdiable byte-streams: 


Local XFrees6 supports local connections via Streams pipe via various 
mechanisms, using the following paths (n represents the 
display number): 

/dev/X/server.n (SVR3 and SVR4) 

/dev/X/Nserver.n (SVR4) 

/dev/Xn$ and /dev/xnR (SCO SVR3) 

In SVR4.0.4, if the Advanced C ompatibility Package is 
installed, and in SVR4.2, xFreese supports local connections 
from clients for SCO XSight/O DT, and (with modifications 
to the binary) clients for ISC SVR3. 

UNIX Domain XFree86 USES /tmp/.X11-unix/Xn as the filename for the socket, 
where n is the display number. 


XF ree86 637 


TCPIP XFrees6 listens on port htons (6ee0+n), wheren is the display 
number. 
Amoeba RPC This is the default communication medium used under native 


Amoeba. N ote that under Amoeba, the server should be 
started with ahostname: displaynumber argument. 


ENVIRONMENT VARIABLES 


For operating systems that support local connections other than UNIX Domain sockets (SVR3 and SVR4), theeisa 
compiled-in list specifying the order in which local connections should be attempted. T his list can be overridden by the 
XLOCAL environment variable described next. If the display name indicates a best-choice connection should be made (for 
example, :@.0), each connection mechanism is tried until a connection succeeds or no more mechanisms are available N ote: 
For theseO Ss, the UNIX Domain socket connection is treated differently from the othe local connection types. To useit 
the connection must be made to unix:0.0. 


The xLocaL environment variable should contain alist of one more of the following: 

NAMED 

PTS 

sco 

Isc 

which represent SVR4 Named Streams pipe, Old-style USL Streams pipe, SCO XSight Streams pipe and ISC Streams pipe, 
respectively. You can select a single mechanism (for example, XLOCAL=NAMED), Or an ordered list, for example, 

XLOCAL="NAMED: PTS: SCO" 

This variable overrides the compiled-in defaults. For SVR4 it is recommended that namep be the first preference connection. 
The default setting is 

PTS: NAMED: 1SC:SCO. 

To globally override the compiled-in defaults, you should define (and export if using sh or ksh) xLocaL globally. If you use 


startx/xinit, the definition should beat the top of your .xinitrc file If you use xdm, the definitions should be early on in 
the <xRoot>/1ib/X11/xdm/Xsession Script. 


OPTIONS 


In addition to the normal server options described in the xserver(1) manual page, xFreesé accepts the following command- 
line switches: 


vtXX xx specifies the Virtual T erminal device number that xFrees6 
will use. Without this option, xFreese will pick the first 
available Virtual T erminal that it can locate T his option 
applies only to SVR3, SVR4, Linux, and BSD OSs with the 
syscons OF pevt driver. 

-probeonly Causes the server to exit after the device probing stage. T he 
xF86Config file is still used when this option is given, so 
information that can be auto detected should be commented 


out. 

-quiet Suppresses most informational messages at startup. 

-bpp n Se& number of bits per pixd. T he default is 8. Legal values are 
8, 15, 16, 24, 32. Not all servers support all values. 

-weight nnn Ses RGB waghting at 16 bpp. The default is 56s. T his applies 
only to those servers that support 16 bpp. 

-gamma valve Sets the gamma correction. val ue must be between 0.1 and 10. 


The default is 1.0. This valueis applied equally to theR, G, 
and B values. N ot all servers support this. 
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-rgamma value 
-ggamma value 
-bgamma value 


-showconfig 


-verbose 


-xf86config file 


-keeptty 


KEYBOARD 


M ultiple key presses recognized directly by xFreese are 
Ctrl+Alt+B ackspace 


Ctrl+Alt+k eypad-Plus 


Ctrl+Alt+K eypad-M inus 








Ctrl +Alt+F 1... F12 


SETUP 


Sets the red gamma correction. value must be betwem 0.1 and 
10. The default is 1.0. N ot all servers support this. 

Sets the green gamma correction. value must be between 0.1 
and 10. The default is 1.0. N ot all servers support this. 


Sets the blue gamma correction. value must be between 0.1 
and 10. The default is 1.0. N ot all servers support this. 


Prints out a list of screen drivers configured in the server. 

M aximizes information printed at startup (more than the 
default). 

Reads the server configuration from file This option is only 
available when the server isrun as root (that is, with real- 
UID 0). 

Prevents the server from detaching its initial controlling 
terminal. T his option is only useful when debugging the 
server. 


Immediately kills the server— no questions asked. (Can be 
disabled by specifying "DontZap" in the Server-Flags section of 
the xFsécontig file) 

Changes video mode to next one specified in the configuration 
file, (increasing video resolution order). 

Changes video mode to previous one specified in the 
configuration file, (decreasing video resolution order). 

For BSD systems using the syscons driver and Linux, these 
keystroke combinations are used to switch to Virtual Console 
1 through 12. 


XFree86 uses a configuration file called xF8éconfig for its initial setup. Refer to the xFs6config(4/5) manual page for more 


information. 


FILES 


<Root>/bin/XF86 SVGA 
<XRoot>/bin/XF86 Mono 
<XRoot>/bin/XF86 S3 
<XRoot>/bin/XF86 Mach8 
<Root>/bin/XF86 Mach32 
<Root>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<Root>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Conf ig 
<Root>/1ib/X11/XF86Config.hostname 
<XRoot>/lib/X11/XF86Config 
<Root>/bin/ 


Thecolor SVGA X server 
ThemonochromeX server for VGA and othe mono cards 
The accelerated s3 X server 

The accelerated Machs X server 

The accelerated mach32 X server 
The accelerated mache4 X server 
The accelerated pge00 X server 

The accelerated aax X server 

The accelerated ET4000/w32 X server 
The accelerated 8514/A X server 
Server configuration file 

Server configuration file 

Server configuration file 

Client binaries 
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<xRoot>/include/ H eader files 

<XRoot>/1ib/ Libraries 

<XRoot>/1ib/X11/fonts/ Fonts 

<XRoot>/1ib/X11/rgb.txt Color namesto RGB mapping 
<XRoot>/1ib/X11/XErrorDB Client error message database 
<XRoot>/1lib/X11/app-defaults/ Client resource specifications 
<XRoot>/man/man?/ M anual pages 

/etc/Xn. hosts Initial access control list for display n 


Note: <xRoot> refers to the root of the X11 install tree. 


SEE ALSO 


X(1), Xserver(1), xdm(1), xinit(1), xF86contig(4/5), xf86config(1), xF86 svGA(1), xF86 VGA16(1), XF86 Mono(1), XF86 Accel(1), 
xvidtune(1) 


AUTHORS 
For x11R5, xF86 1.2 was provided by the following: 


Thomas Rod (roe11@informatik.tu-muenchen.de; server and SVR4 stuff), M ark W. Snitily (mark@sgcs.com sacs; SVR3 
support, X Consortium Sponsor), and many more people out there on the N & who heaped with ideas and bug fixes. 


XFrees6 was integrated into x11R6 by the following team: 


Stuart Anderson (anderson@metrolink.com), Doug Anson (danson@igc.com), Gertjan Akkerman 
(akkerman@dutiba.twi.tudelft.nl), Mike Bamnson (mike@mbsun.mlb.org), Robin Cutshaw (robinexFree86.org), D avid D awes 
dawes@xFree86.org), M arc Evans (marcexFree86. org), Pascal H aible (haible@izfm.uni-stuttgart.de), Matthieu H errb 
Matthieu.Herrb@laas.fr), Dirk Hohndd (hohndele@xFree86.org), D avid H olland (davidh@use.com), Alan H ourihane 
alanh@fairlite.demon.co.uk), Jeffrey H Su (hsu@soda.berkeley.edu), Glenn Lai (glenn@cs.utexas.edu), T ed Lemon 
mellon@ncd.com), Rich M urphey (richexFree86.org), H ans N asten (nasten@everyware.se), M ark Snitily (mark@sgcs.com), 
Randy T erbush (randyt@cse.unl.edu), Jon Tombs (tombs@xFrees6.org), K ees Verstoep (versto@cs.vu.ni), Paul Vixie 
(paul@vix.com), M ark W eaver (Mark Weaver@brown.edu), D avid W exelblat (dwexexFree86.org), Philip Wheatley 

(Philip .Wheatley@ColumbiaSC.NCR.COM), T homas Wolfram (wolf@prz.tu-berlin.de), and O rest Zborowski 
(orestz@eskimo.com). 


omy om cama are 


The xFree86 enhancement package was provided by 


D avid D awes, dawes@xFree86.org Release coordination, administration of FTP repository and 
mailing lists. Source tree managanent and integration, 
accd erated server integration, fixing, and coding. 


Glenn Lai, glenn@cs.utexas.edu The SpeedU p code for ET4000-based SVGA cards, and ET4000/ 
w32 accderated server. 

Jim Tsillas, jtsilla@ccs.neu.edu M any server speedups from the fX 386 series of enhancements. 

D avid Wexelblat, dwexexFree86. org Integration of the fX 386 code into the default server, many 


driver fixes, and driver documentation, assembly of the VGA 
card/monitor database, development of the generic video 
mode listing. Accelerated server integration, fixing, and 
coding. 

Dirk H ohndd, hohndelexFree86.org Linux-shared libraries and release coordination. Accderated 
server integration and fixing. G eneric administrivia and 
documentation. 

Amancio H asty Jr., hasty@netcom. com Porting to 386BSD version 0.1 and XS3 devdopment. 


Rich M urphey, richexFree86. org Ported to 386BSD version 0.1 based on the original port by 
Pace Willison. Support for 386BSD , FreeBSD, and NetBSD. 


Part |: User Commands 


Robert Baron, Robert.Baron@ernst.mach.cs.cmu.edu 

O rest Zborowski, orestz@eskimo.com 

Doug Anson, danson@lgc.com 

David Holland, davidheuse.com 

David McCullough, davidm@stallion.oz.au 

M ichad Rohleder, michael. rohleder@stadt-frankfurt.de 
Kees Verstoep, versto@cs.vu.nl 


M arc Evans, Marc@xFree86.org 

Philip Homburg, philip@cs.vu.n1 

Thomas M ueller, tmésystrix.de 

Jon Tombs, tombsexFree86.org 

H arald Koenig, koenig@tat.physik.uni-tuebingen.de 
Bernhard Bendé,, br@elsa.mhs.compuserve.com 
Kevin Martin, martin@cs.unc.edu 


Rik Faith, faithecs.unc. edu 
Tiago Gons, tiago@comosjn.hobby.nl 
H ansN asten, nasten@everyware.se 


Mike Bernson, mike@mbsun.mlb.org 

M ark W eave, Mark Weaver@brown. edu 

Craig Groeschel, craig@metrolink.com 

H enry Worth, Henry .Worth@amail.amdahl.com 
Erik N ygren, nygrenemit.edu 

H arry Langenbacher, harry@brain. jpl.nasa.gov 
ChrisM ason, mason@mail.csh.rit.edu 

H enrik H armsen, harmsen@eritel.se 

Simon Cooper, scooper@vizlab.rutgers.edu 
H arm H anemaaye’, hhanemaa@cs. ruu.nl 

Mike Tierney, floyd@eng.umd.edu 

Bill Conn, conn@bnr.ca 

Brad Bosch, brad@lachman. com 

Alan H ourihane, alanh@fairlite.demon.co.uk 
M arc LaFrance, Marc.La-France@ualberta.ca 
Steve Goldman, sgoldman@encore.com O ak 
Jorge D elgado, ernar@dit.upm.es 

Bill Conn, conn@bnr.ca 

Paolo Severini, lendl@dist.dist.unige.it 
Ching-T ai Chiu, cchiu@netcom. com 

Manfred Brands, mb@oceonics.nl 

Randy H endry, randy@sgi.com 

Frank Dikker, dikker@cs.utwente.nl 
RegisCridlig, cridlig@dmi.ens.fr 

Jon Block, block@fre.com 


Ported to M ach. 
Ported to Linux. 
Ported to Solaris x86. 
Ported to Solaris x86. 
Ported to SCO SVR3. 
Ported to ISC SVR3. 


Ported to Amoeba based on Leendert van D oorn’s original 
Amoeba port of X11R5. 


Ported to OSF/1. 

Ported to M inix-386vm. 

Ported to Lynx0 S. 

S3 server and accelerated server coordination. 
S3 server development. 

S3 server development. 


Overall work on the base accelerated servers (AT! and 8514/ 
A), and M ach64 server. 


O verall work on the base accelerated servers (ATI and 8514/A),. 
M ach8 and 8514/A server development. 


M ach8, 8514/A, and S3 server development and BSD /386 
support. 


M ach32 server development. 

M ach32 server development. 

M ach32 server development. 

AGX server. 

P9000 server. 

P9000 server. 

P9000 server. 

P9000 server. 

Cirrus accderated code (based on work by Bill Reynolds). 
Cirrus accelerated code and ARK driver. 

WD accderated code. 

WD accderated code. 

WD 90C 24A support. 

Trident SVGA driver 

ATI vgawonder SVGA driver 

067/077 SVGA driver. 

Oak SVGA driver, and 087 accelerated code 
WD accderated code. 

AL2101 SVGA driver. 

Avance Logic ALI SVGA drive. 

Cirrus 64xx SVGA driver. 

Cirrus 6440 support in the cl64xx SVGA driver. 
MX SVGA driver. 

Chips & Technology driver. 

Chips & Technology driver. 


MikeH ollick, hollick@graphics.cis.upenn.edu Chips & Technology driver 

Peter T rattler, peter@sbox.tu-graz.ac.at RealT ek SVGA driver. 

Craig Struble cstruble@acm. vt.edu Video7 SVGA driver. 

Gertjan Akkerman, akkerman@dutiba.twi.tudelft.n1 16-color VGA server, and XF86C onfig parser. 

Davor M atic, dmatic@Athena .MIT.EDU H ercules driver. 

Pascal H aible, haible@izfm.uni-stuttgart .de Banked monochromeV GA support, H ercules support, and 


mono frame buffer support for dumb monochrome devices. 
and many more people out there on the N & who hdped with beta-testing this enhancement. 
XFree86 source is available from the FT P server ftp.xFree86.org, among others. Send email to xFrees6e@xFree86.org for 
details. 
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xfs— X font server 


SYNOPSIS 

xfs [-config configuration file] [-port tcp_port ] 
DESCRIPTION 

xfs istheX Window System font server. It supplies fonts to X Window System display servers. 
STARTING THE SERVER 


The serve is usually run by a system administrator, and started via boot files like /etc/rc.1local. Users may also wish to start 
private font servers for specific sets of fonts. 


OPTIONS 
-config configuration file Specifies the configuration file the font server will use. 
-1s listen-socket Specifies a file descriptor that is already set up to be used as the 


listen socket. This option is only intended to be used by the 
font server itself when automatically spawning another copy of 
itself to handle additional connections. 

-port tcp_port Specifies the TCP port number on which the server will listen 
for connections. 


SIGNALS 
SIGTERM This causes the font server to exit cleanly. 
SIGUSR1 This signal is used to cause the server to reread its configura- 
tion file 
SIGUSR2 This signal is used to cause the server to flush any cached data 
it may have 
SIGHUP This signal is used to cause the server to reset, closing all active 


connections and rereading the configuration file 
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CONFIGURATION 
The configuration language is a list of keyword and value pairs. Each keyword is followed by an = and then the desired value. 
Recognized keywords include the following: 


catalogue (list of string) Ordered list of font path element names. Use of the key-word 
“catalogue” is very misleading at present; the current 








implenentation only supports a single catalogue (a11), 
containing all of the specified fonts. 

alternate-servers (list of string) List of alternate servers for this font server. 

client-1imit (cardinal) N umber of clients this font server will support before refusing 
service. This is useful for tuning the load on each individual 
font server. 

clone-self (Boolean) Whether this font server should attempt to clone itsdf when it 
reaches the client - limit. 

default -point-size The default pointsize (in decipoints) for 

(cardinal) fonts that don’t specify. The default is 120. 

default -resolutions Resolutions the server supports by default. 

(list of resolutions) This information may be used as a hint for 


prerendering, and substituted for scaled fonts that do not 
specify a resolution. A resolution isa comma- 

separated pair of x and y resolutions in pixels 

per inch. M ultiple resolutions are separated by commas. 


error-file (string) Filename of the error file. All warnings and errors will be 
logged here. 

port (cardinal) TCP port on which the serve will listen for connections. 

use -syslog (Boolean) Whether syslog(3) (on supported systems) is to be used for 
errors. 

deferglyphs (string) Seé the mode for delayed fetching and caching of glyphs. Value 


iSnone, meaning deferred glyphs is disabled, a11, meaning it is 
enabled for all fonts, and 16, meaning it is enabled only for 16- 


bits fonts. 
# 
# sample font server configuration file 
# 
# allow a max of 10 clients to connect to this font server client-limit = 10 
# when a font server reaches its limit, start up a new one clone-self = on 
# alternate font servers for clients to use alternate-servers = hansen:7101,hansen:7102 
# where to look for fonts 
# the first is a set of Speedo outlines, the second is a set of 
# misc bitmaps and the last is a set of 10Qdpi bitmaps 


# 

catalogue = /usr/X11R6/1ib/X11/fonts/speedo, 
/usr/X11R6/1ib/X11/fonts/misc, 
/usr/X11R6/1ib/X11/fonts/100dpi/ 

# in 12 points, decipoints 
default-point-size = 120 

# 100 x 100 and 75 x 75 

default-resolutions = 100,100,75,75 
use-syslog = off 


xhost fe 


FONT SERVER NAMES 
One of the following forms can be used to name a font server that acceots TCP connections: 


tcp/hostname: port tcp/hostname: port /cataloguelist 


Thehostname specifies the name (or decimal numeric address) of the machine on which the font server is running. Theport 
is the decimal TCP port on which the font server is listening for connections. Thecataloguelist specifies alist of catalogue 
names, with + as a separator. 


Examples: tcp/fs.x.org:7100, tcp/18.30.0.212:7101/all. 
One of the following forms can be used to namea font server that acceots DEC net connections: 


decnet/nodename::font$obj name decnet/nodename::font$obj name /catal oguelist 


Thenodename specifies the name (or decimal numeric address) of the machine on which the font sever is running. The 
obj name iSanormal, case-insensitive D EC net object name. Thecatal oguelist specifies alist of catalogue names, with + asa 
separator. 


Examples: DECnet/SRVNOD: : FONT$DEFAULT, decnet/44.70: :font$special/symbols. 


SEE ALSO 


x(1), font server implementation overview 


BUGS 
M ultiple catalogues should be supported. 


AUTHORS 
D ave Lemke (N etwork Computing D evices, Inc.), Kath Packard (M assachusetts Institute of T echnology) 
X Verson 11 Release 6 
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xhost— Server access control program for X 


SYNOPSIS 


xhost [[+-]name ...] 


DESCRIPTION 


The xhost program is used to add and delete hostnames or usernames to the list allowed to make connections to the X server. 
In the case of hosts, this provides a rudimentary form of privacy control and security. It is only sufficient for a workstation 
(single user) environment, although it does limit the worst abuses. Environments that require more sophisticated measures 
should implenent the user-based mechanism or use the hooks in the protocol for passing other authentication data to the 
server. 


OPTIONS 


Xhost accepts the following command-line options. For security, the options that effect access control may only be run from 
the “controlling host.” For workstations, this isthe same machine as the server. For X terminals, it isthe login host. 


-help Prints a usage message. 


[+]name The given name (the plus sign is optional) is added to the list 
allowed to connect to the X server. Thenamecan bea 
hostname or a username. 
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-name Thegiven name isremoved from the list allowed to connect to 
the server. Thename can bea hostname or a username 
Existing connections are not broken, but new connection 
attempts will be denied. N ote that the current machine is 
allowed to be removed; howeve,, further connections 
(including attempts to add it back) will not be permitted. 
Resetting the server (thereby breaking all connections) isthe 
only way to allow local connections again. 

+ Access is granted to everyone, even if they aren't on thelist (in 
other words, access control isturned off). 

z Access is restricted to only those on the list (that is, access 
control is turned on). 

nothing If no command-line arguments are given, a message indicating 
whether or not access control is currently enabled is printed, 
followed by the list of those allowed to connect. Thisis the 
only option that may be used from machines other than the 
controlling host. 


NAMES 
A complete name has the syntax f ami | y :name where the families are as follows: 
inet Internet host 
dne DECneé& host 
nis SecureRPC network name 
krb KerberosV 5 principal 
local Contains only one name, the empty string 


The family is case insensitive The format of the name varies with the family. 


W hen Secure RPC is bang used, the nework-independent netname (for example, nis:unix.uid@domainname) can be 
specified, or alocal user can be specified with just the username and atrailing at sign (@) (for example, nis: pate). 


For backward compatibility with pre R6 xhost, names that contain an at sign are assumed to bein thenis family. O therwise 
the inet family is assumed. 


DIAGNOSTICS 


For each name added to the access control list, aline of the form name being added to access control list is printed. For 
each name renoved from the access control list, aline of the form name being removed from access control list is printed. 


FILES 


/etc/X*. hosts 


SEE ALSO 


X(1), Xsecurity(1), Xserver(1), xdm(1) 


ENVIRONMENT 
DISPLAY To ge@ the default host and display to use 


BUGS 


You can’t specify a display on the command line because -display is a valid command-line argument (indicating that you 
want to remove the machine named display from the access list). 


xieoet 


TheX server stores network addresses, not hostnames. T hisis not really a bug. If somehow you changea host’s network 
address while the server is still running, xhost must be used to add the new address and/or remove the old address. 


AUTHORS 
Bob Schafler (MIT Laboratory for Computer Science) and Jim Gettys (MIT Project Athena/D EC) 
X Verson 11 Release 6 
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xieperf— XIE server extension test and deno program 


SYNTAX 
xieperf [-option ...] 
DESCRIPTION 


The xieperf program is based upon rs x1t1perf(1) , and whilenot entirely comprehensivein its coverage of the x1e protocol 
(see the “Bugs” subsection), it isintended to be useful in the evaluation of x1e implementations in the areas of protocol 
adherence and performance. The xieperf program includes tests that execute each of the protocol requests and photoflo 
elements specified by revision 5.0 of thexre protocol. In addition, xiepert provides a set of tests that can be used to validate 
the detection and transmission of x1e protocol request errors, such as FIoM atch, FloValue, and so forth. Finally, xiepert 
provides a customizable demonstration program for xzE. 


A test is made up of three components executed in sequence: an initialization function, a test function, and an end function. 
Theinitialization function is responsible for allocating and populating test resources, such as photomaps and LUT s, and for 
creating a stored photoflo that will be executed by the test function. The test function, in most cases, simply executes the 
stored photoflo for a specified number of repetitions. The end function, which is called following thetest function, is used 
primarily to destroy any noncacheable server resources used by the test, and to free any memory that was dynamically 
allocated by the client. Some tests, such a -modify1, -await, -abort, aNd -redefine, perform additional steps within the test 
function inner loop, as required by the element being tested, or in an attempt to make the test more visually appealing. 


Evaluating the performance of individual x1e elenents is not as simple as measuring Core X drawing times. The x1e protocol 
requires dements to be enbedded within photoflosin order to be exercised, and the minimum possible photoflo sizeis two. 
This implies that it is impossibleto measure performance of a single element in isolation— thetime it takes to run the flo 
depends on what other elements exist in the flo. Extrapolating performance of a single element (or technique) in a flo must 
be done carefully, on a case-by-case basis, because in general, measured dement performance depends on input image size, 
data type, and other factors, all of which can be influenced by upstream flo elements. N ote further that the number and type 
of elements in a flo can be influenced by the visuals available on the display, so even flo-flo comparisons on machines with 
different visuals must be done with caution. 


M any test labels contain an abbreviated pipeline description. For instance, 1P/1L/P/ED indicates ImportPhotomap, ImportLuT, 
Point, and ExportDrawable. Pipelines ending in ep (ExportDrawable) often include hidden elements such as Bandextract, 
ConvertToIndex, Dither, OF Point to match the flo output to the screen visual. Pipelines ending in EP (ExportPhotomap) will 
result in a blank window. 


xieperf is compatible with x11perfcomp(1), which is used to compare the outputs of different xiepert and x11perf runsina 
nice, tabular format. In xieperf you will need to use the -1abels option (see the “O ptions” subsection), and provide the 
resulting labels file to x11perfcomp(1) to obtain correct output. See the x11perfcomp(1) man pages for more details on this. 
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OPTIONS 


xieperf accepts the following options: 


-display host:dpy 
-images <path> 


-timeout<s > 


-sync 
-script <file> 


-repeat <n> 


-time <s > 


-depth <depth> 


-GrayScale 
-PseudoColor 
-StaticGray 
-StaticColor 
-TrueColor 
-DirectColor 
-WMSafe 


Specifies which display to use 

Normally, xiepert references image files located in the 
directory images, which xieperf assumes is located in your 
current directory. If the images directory isnot in your current 
directory, or the filehas been renamed, use this option to 
specify its location. 

Sometests require the reception of an event such as FloNotify 
to continue and may cause xieperf to hang should these 
events not be received. T his option allows the user to specify a 
time-out value which, if exceeded, will cause xieperf to give 
up waiting for an event, and continue on with the next test in 
sequence. Should an event time-out, a warning message will be 
printed to stderr. The default timeout value is 60 seconds. 
Runs the tests in synchronous mode 

Using this option gives the user the ability to run a subset of 
the available tests and control the number of times the tests are 
executed on an individual basis. This is thought to be 
especially useful for thoserunning xieperf for demonstration 
purposes. U sing this option causes xieperf to read commands 
specified in a script file, or from stain if <file>is -. T ests are 
specified by newline-terminated input lines of the form 
command [-reps n ] [ -repeat m ]. Characters following and 
including # are treated as comments. See the -mkscript option. 
Repeats each test n times (by default each test is run two 
times). This option may be used in script files also, in which 
case the script file -repeat overrides the command-line option. 
Specifies how long in seconds each test should be run (default 
5 seconds). 

Usea visual with <depth> planes per pixel (default is the 
default visual). 

Use a GrayScale visual (default is the default visual). 

Use a PseudoColor visual (default is the default visual). 

Use a StaticGray visual (default is the default visual). 

Use aStaticColor visual (default is the default visual). 

Use a TrueColor visual (default is the default visual). 

Use a DirectColor visual (default is the default visual). 

If xieperf Must berun in a window manager environment, use 
this flag to make xieperf aware of this. If specified, xiepert 
will create a window, identical to the size of the root window, 
and all further windows created by xieperf will be transient 
pop-up children of this window. If this flag is omitted, xieperf 
will set the override_redirect attribute of all windows to True 
and will also do evil things such as calling xtnstal1colormap. 
Using this option will cause the window manager to (hope 
fully) obey window geometry hints specified by xieperf. 


-showtechs 


-showlabels 


-showevents 


-events 
-errors 
-loCal 


-all 


-tests 


-mkscript 


-cache <n> 


-labels 


-DIS 


-range <test1l>[,<test2>] 


xieoet 647 


Display a comprehensive list of techniques, by category, 
indicating which of the techniques are supported by thexie 
server. 


Print test label to screen prior to calling any of the test code 
This allows the user to know which test is executing in case the 
test hangs for some reason. 

Be verbose when running event and error tests. Also, can be 
used to catch and display information on any signals received 
during execution of xieperf. N ote that this flag is best used in 
a debugging situation, or to validate that the error events 
received by xiepert are valid the first time the tests are 
executed on anew platform. 

Run tests that test for event generation. 

Run tests that test for error event generation. 

Skip test calibration. This may be used when running xieperf 
in situations where execution timing is not important. 
Execution times will not be reported by xiepert when this 
option is enabled. The inner loop repeat count, additionally, is 
set to a value of 5 (but can be overridden by the -reps option). 
Runs all tests. This may take a while depending on the speed 
of your machine, and its floating-point capabilities. T his 
option is ignored if a script file is used. 

Generate a list of the available tests for the xieperf program. 

In x11perf, this list is normally displayed in the usage 
statement. It was yanked from the usage of xieperf because it 
was too lengthy. 

Generate a script file suitable for use with the script option. If 
-repeat OF -reps are also specified, they will be automatically 
placed at the end of each command in the script. The script is 
generated to stderr. Seethe -script command, above. 

M ost test flos utilize a photomap resource for a source A 
photomap cache of up to n entries is controlled by xiepert to 
avoid having to constantly reload these images during test 
initialization. The default cache size is 4. If a value less than the 
default is specified, the cache size will be set to the default. 
Generates just the descriptive labels for each test specified. Use 
-all Or -range to specify which tests are included. See 
x11perfcomp(1) for more details. 

Pretend we are running xieperf while connected to a p1s-only 
capableimplementation of x1e. T his will cause xiepert to 
execute those tests that only use protocol requests found in the 
pis subset of x1e, and bypass those which are not p1s- 
compatible If xieperf detects apis serve, it will do this 
automatically, and this option is ignored. Use -a11 or -range to 
specify the initial range of tests. 

Runs all the tests starting from the specified name ted until 
thenametes2, including both the specified tests. Some tests, 
like the event and error tests, also require the -errors or - 
events options to specified. This option isignored if ascriptis 
used. 
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-reps <n> 


-ImportObscuredEvent 
through -ExportAvailable 


-BadValue through 
-FloValueError 


-ColorList 

-LUT 

-Photomap 

-ROI 
-Photospace 
-Photoflo 
-QueryPhotomap 
-QueryColorList 


-QueryTechniquesDefault 
through -queryTechniques 
WhiteAdjust 


-QueryPhotof lo 
-PurgeColorList 
-Abort 


-Await 


-importclientlut1 


-importclientphoto1 through 
-importclientphoto9 


-importclientroil 
-importclientroi2 


-encodephoto1 through 
-encodephoto14 


Fix the inner loop repetitions to n. This indicates how many 
times the photoflo will be executed each timethe test is run. 
This option is overridden on a per test basis if specified in a 
script. Typically, xieperf determines the ideal number of reps 
during each test’s calibration period. 


Test generation of events. Requires - events flag. 


T est generation of errors. Requires -errors flag. 


Create anddestroy colorList resource test. 
Create and destroy Lut resource test. 
Create and destroy Photomap resource test. 
Create and destroy ror resource test. 
Create and destroy Photospace test. 

Create and destroy Photof1o test. 

Query Photomap resource test. 

Query ColorList resource test. 

Query techniques as specified by test name. 


Query Photoflo test. 
Purge ColorList test. 


This test creates a photoflo that is started and blocks for data 
provided by PutClientData(). Instead of sending the data, the 
test USES XieAbort() to stop the photoflo, and then waits for 
the PhotofloDone event to be sent by the serve. If the test times 
out waiting for the event, an error message is sent to stderr. 


This test creates a flo of theform ImportClientLUT -> 
ExportLuT, and starts the flo executing. xieperf then forks, and 
the child process streams the LUT data to the flo using 
PutClientData, while the parent blocks in xieawait. If the flo 
successfully finishes, xieAwait will return and the flo state, after 
query, will indicate that it has completed. If xieawait does not 
complete naturally, or after return from XieAwait the flo is still 
active, an error is reported to stderr. N ote on a really slow 
machine, it is possible that xieAwait will return before the flo 
has a chance to finish. In this case, use the -timeout option to 
increase the time-out for this test. 

ImportClientLUT -> ExportLuT test. 

Flos of the form ImportClient-Photo -> ExportPhotomap USING 
various decode techniques, for example, 6320, TIFF2, 
UncompressedTriple 

ImportClientRol with 10 rectangles. 

ImportClientror with 100 rectangles. 

Flos of the form ImportPhotomap - ExportPhotomap using 
various encode techniques, for example 32D, TIFF2, 
UncompressedTriple. O riginal encoding is shown in left 
window; image after encoding is shown in right window. 


-encodeclientphoto1 through 
-encodeclientphoto11 


-exportclientlut1 
-exportclientroil 


-exportclientroi2 
-exportclienthistogram1 
through 
-exportclienthistogram4 
-exportclienthistogramroit 
through 
-exportclienthistogramroi4 
-exportclienthistogramcplane1 
through 


-exportclienthistogramcplane4 








-importlut1 
-importphoto1 


-importphoto2 


-importroil 


-importroi2 


-importdrawable1 


-importdrawable2 


-importdrawable3 


-importdrawable4 


-importdrawable5 


-importdrawable6 


-importdrawable7 








-importdrawable8 


-constraint 


Two flos, oneof theform ImportPhotomap -> 

ExportClientPhoto, and the other of the form 

ImportClientPhoto -> ExportPhotomap, where 

ExportClientPhoto in the first flo uses various encode 
techniques, for example G32D, TIFF2, UncompressedTriple. The 
image before encoding is displayed in the left window, while 
the right window shows the image that was encoded in the 
first flo and read back in the second flo. 

ExportClientLuT test. LUT is displayed in a histogram window. 
ExportClientror test, 10 ROIs. TheROIsthat are sent to the 
server are represented by the filled rectangles. The ROIs that 
are received back from the server by the client are drawn as 
white bordered, nonfilled rectangles. T he resulting output 
illustrates how the server combined the rectangles sent to it. 
Same aS exportclientroi1, except using 100 rectangles. 


ExportClientHistogram tests using various images. T he 
histogram is displayed in a window that overlaps the image. 





Same as the ExportClientHistogram test, but usingaRO| 
to identify the area of interest. 


Same as the ExportClientHistogram test, but using a 
control plane to identify the area of interest. 


Test ImportLut dement; LUT sizeis 256. 

ImportPhotomap -> ExportPhotomap, with source and destina- 
tion equal. 

ImportPhotomap -> ExportDrawable, window destination. 


ImportROI -> ExportROI, 10 rectangles, source and destination 
ROIs equal. 

ImportROI -> ExportROI, 100 rectangles, source and destination 
ROIs equal. 


ImportDrawable -> ExportDrawable, Sourceis pixmap, 
destination is window. 


ImportDrawable -> ExportDrawable, source and destination are 
both window. 


ImportDrawable -> ExportDrawable, destination window 
obscured by source window. 


ImportDrawable -> ExportDrawable, Source window obscured 
by destination window. 


ImportDrawablePlane -> ExportDrawablePlane, pixmap, source 
= destination. 


ImportDrawablePlane -> ExportDrawablePlane, Window, source 
= destination. 


ImportDrawablePlane -> ExportDrawablePlane, Window, source 
obscures destination. 


ImportDrawablePlane -> ExportDrawablePlane, window, 
destination obscures source. 


Constrain Hardclip technique test, drawable destination. 
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-constrain2 


-constrainphoto1 


-constrainphoto2 


-convolve1 


-convolve2 


-convolve3 


-convolve4 


-convolveroit 


-convolveroi2 


-convolvecplane1 


-convolvecplane2 
-matht through -mathcplane7 


-ari 


hmeticdyadic1 through 


-arithmeticdyadic5 


-ari 


hmeticmonadic1 through 


-arithmeticmonadic9 


-ari 


hmeticdyadicroil 


through 


arithmeticdyadicroid5 


-ari 


hmeticmonadicroi1 


through 


-ari 


-ari 


hmeticmonadicroi9 


hmeticdyadiccplane1 


through 


-ari 


-ari 


hmeticdyadiccplane5 


hmeticmonadiccplane1 


through 


-ari 


-ari 


hmeticmonadiccplaneg 


hmeticfloatdyadict 


though 


-ari 


-ari 


hmeticfloatdyadic5 
hmeticfloatmonadic1 


though 


-ari 
-ari 
to 
-ari 
-ari 
to 





hmeticfloatmonadicg 
hmeticroifloatdyadic1 


hmeticroifloatdyadic5 


hmeticroifloatmonadic1 


-rithmeticroifloatmonadic9 
-band1 


Constrain clipScale technique test, drawable destination. 
Constrain Hardclip technique test, photomap destination. 
Constrain clipScale technique test, photomap destination. 
Boxcar 3x3 convolution test. Smoothing or lowpass filter. 
Boxcar 5x5 convolution test. Smoothing or lowpass filter. 
LaPlacian 3x3 convolution test. Edge or highpass filter. 
LaPlacian 5x5 convolution test. Edge or highpass filter. 
LaPlacian 3x3 convolution test, with ROI. 

LaPlacian 5x5 convolution test, with ROI. 

LaPlacian 3x3 convolution test, with control plane 
LaPlacian 5x5 convolution test, with control plane 


Various tests that exercise the math element, some tests using 
ROIsand control planes. 


Arithmetic element tests, using photomaps 
as the operands. 
Arithmetic element tests, photomap and constant operands. 





Arithmetic element tests, using - photomaps asthe 
operands, with RO Is. 


Arithmetic element tests, photomap and 
constant operands, with ROIs. 


Arithmetic element tests, using photomaps as the 
operands, with control planes. 


Arithmetic element tests, photomap and constant 
operands, with control planes. 


Arithmetic element tests, using photomaps 
as the operands, unconstrained. 


Arithmetic element tests, photomap and constant 
operands, unconstrained. 


Arithmetic element tests, photomaps as the 
operands, ROIs, unconstrained. 





Arithmetic element tests, photomap and 
constant operands, ROIs, unconstrained. 





BandSelect element test. Image input is triple band. If visual of 
xieperf window is acolor visual, then three Band-Select 
elements are used to extract the individual bands; they are 
combined once again using BandCombine, and displayed using 
ConvertToIndex. If the visual is not color, for example, 
GrayScale Or StaticGray, then the flo simply uses one 
BandSelect element to extract a single band for display. 


-band2 


-band3 


-band4 


-band5 


-comparedyadic1 through 
-comparedyadic6 
-comparemonadict through 
-comparemonadic6 
-compareroidyadict through 
-compareroidyadic6 
-compareroimonadic1 through 
compare compareroimonadic6 
-comparecplanedyadict 
through 
-comparecplanedyadic6 
-comparecplanemonadic1 
through 
-comparecplanemonadic6 
-matchhistogram1 

through 
-matchhistogram18 
-matchhistogramroit 
through 
-matchhistogramroié 
-matchhistogramcplane1 
through 


-matchhistogramcplane6 





-unconstrain1 


-pasteup1 through -pasteup2 
-geometry1 through 
-geometry14 

-geometry15 through 
-geometry28 

-geometry29 through 
-geometry42 
-geomg3{dscale1 through 
-geometryfaxradio1 
-dither1 

-dither2 
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BandCombine test. Input bands are made of three separate single 
band photomaps. T hese are combined using a BandCombine 
element, which is followed by aBandextract and 
ExportDrawable. CCIR 601-1 coefficients. 

BandExtract test. Input isa triple band photomap. CCIR 
601-1 coefficients. D estination window colormap is gray ramp. 
BandExtract test. Input isa triple band photomap. CCIR 
601-1 coefficients. D estination window colormap is rGB BEST 
map standard colormap. 

BandExtract test. Input isa triple band photomap. CCIR 
601-1 coefficients. D estination window colormap is 
RGB_DEFAULT_MAP standard colormap. 

T est various compare operators with dyadic 

photomap operands. 

T ett various compare operators with photomap, 

constant operands. 

Test various compare operators with dyadic photomap 
operands, using ROIs. 

T ett various operators with photomap, 

constant operands, using ROIs. 

T est various compare operators with dyadic 

photomap operands, control planes. 





Test various compare operators with photomap, 
constant operands, control planes. 


MatchHistogram Aanent tests, using various 
images and histogram matching techniques. 


A selection of matchHistogram element 
tests, with ROIs. 


A selection of M atchH istogram denent 
tests, with control planes. 


ImportPhotomap, Unconstrain, Constrain(ClipScale), 
ExportDrawable test. 


Pasteup dement tests. 


Geometry element tests, including rotations, scales, 
and mirroring. NearestNeighbor technique. 


Geometry element tests, including rotations, scales, 
and mirroring. AntiAlias technique. 


Geometry element tests, including rotations, scales, 
and mirroring. BilinearInterpolation technique. 


Tests to exercise the various FAX decoders and 
the Geometry element. 


Dither test, ErrorDiffusion dither technique, ExportDrawable. 


Dither test, ErrorDiffusion dither technique, 
ExportDrawablePlane. 
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-dither3 

-dither4 

-dithers 

-dither6 

-dither7 

-dither8 

-logicalmonadict through 
-logicalmonadic16 
-logicaldyadic1 through 
-logicaldyadic16 
-logicalmonadicroit through 
-logicalmonadicroi16 
-logicaldyadicroi1 through 
-logicaldyadicroi16 
-logicalmonadiccplane1 
through 
-logicalmonadiccplane16 
-logicaldyadiccplane1 
through 
-logicaldyadiccplane16 
-blend1 





-blend2 
-blendroit 


-blendroi2 


-blendcplanet 


-blendcplane2 


i 
oa 


endalpha1 


oa 


endalpha2 


oa 


endalpharoil 





-blendalpharoi2 


-triplepoint1 through 
-triplepoint2 
-funnyencode1 through 
-funnyencode8 


Dither test, Ordered(4 


(4) dither technique, ExportDrawable. 
Dither test, Orderea(4 

( 

( 


dither technique, ExportDrawablePlane. 
Dither test, Ordered(8) dither technique, ExportDrawable. 
Dither test, Ordered(8) dither technique, ExportDrawablePlane. 
Dither test, D efault dither technique, ExportDrawable. 

Dither test, D efault dither technique, ExportDrawablePlane. 
Logical Aement, photomap and a constant 

of 0 as operands, various operators. 

Logical element tests, dyadic photomaps as 

operands, various operators. 

Logical Aement, photomap and constant of 

0 operands, various operators, ROIs. 

Logical element, dyadic photomaps as operands, various 
operators, ROIs. 

Logical element, photomap and constant of 0 

operands, various operators, C ontrol Planes. 


oe eye 


Logical element, dyadic photomaps as operands, 
various operators, control planes. 


Blend element test. M onadic source, 0.1 source constant. 
Alpha constant of 0.5. 
B 
B 


end element test. D yadic sources. Alpha constant of 0.5. 
end test. M onadic source, 0.1 source constant. Alpha 
constant of 0.5. ROIs. 

Blend element test. D yadic sources. Alpha constant of 0.5. 
UsesROIs. 


end test. M onadic source, 0.1 source constant. Alpha 
constant of 0.5. control plane 

end element test. D yadic sources. Alpha constant of 0.5. 
control plane. 


end test. M onadic source, 220 source constant. Alpha plane 
a photomap. 


end test. D yadic sources. Alpha plane is a constant 220. 


end test. M onadic source, 220 source constant. Alpha plane 
hotomap. ROIs. 

end test. D yadic sources. Alpha plane is a constant 220. 

Ols. 

Illustrate use of point and standard colormaps 

for rendering triple band images. 

T hese tests are designed to perform limited exercising of XIE’s 
capability of dealing with various encodings of flo source data. 
Thetest init function obtains a photomap using 1cp -> Ep.A 
series of independent permanent flo pairs, one of the form 1p 
-> Ep, and the other of the basic form 1p -> ep, are con- 
structed. T he encoding parameters for the ExportPhotomap (EP) 
element in the first flo are derived from test configuration. The 
number of flo pairs created is also dependent upon test 
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configuration. T he tests can be configured so that the test init 
function will constrain theinput photomap to a specified 
number of levds, on aper band basis, so that word-sized and 
quad-sized pixels are passed through the flos. Some tests below 
take advantage of this. See tests.c for test configuration, and 














hints on how to add similar tests. 

-point1 through -point3 Simple Point element tests. D rawable destination. 

-pointroit Simple Point aement test that uses ROIs. D rawable destination. 

-pointcplane1 Simple Point element test that uses a control plane. D rawable 
destination. 

-pointphotot1 Simple Point element test. Photomap destination. 

-pointroiphoto1 Simple Point element test that uses ROIs. Photomap 
destination. 

-pointcplanephoto1 Simple Point element test that uses a control plane. Photomap 
destination. 

-redefine Two flographs are created that are the same in structure, 
except for the x and y offsets specified for the ExportDrawable 
flo deanents. T he test init function creates a photoflo based 
upon one of the two flographs. The inner loop of the test 
function uses XieRedefinePhotof1o() to alternate between each 
of the flographs. M ake sure that your inner loop reps are 2 or 
greater in order to exercise this test fully (see -reps). 

-modify1 T est XieModifyPhotoflo() by adjusting RO! offsets and size. 

-modify2 T est XieModifyPhotoflo() by changing the LUT input to a 
Point element. 

-modify3 T est XieModifyPhotoflo() by changing ExportDrawable x and y 
offsets. 

-modify4 This test creates a rather long flo of arithmetic elanents, each 


of which does nothing more than add 1 to asmall image The 
test init function scalestheinput photomap. The 
ExportDrawable x and y offset is modified randomly during 
each iteration of the test function inner loop. 

-modify5 This test creates a rather long flo of arithmetic dements, each 
of which does nothing more than add 1 to a large image. Each 
rep, the Geometry and ExportDrawable Aanents at the end of 
the flo are modified to crop a small piece of the input into its 
appropriate place in the larger image. 

-rgb1 through -rgb16 T hese tests all basically take an UncompressedTriple image as 
input, send it to convertFromras, which converts the image to 
some configured colorspace, and then send the converted 
image on to ConvertTores prior to display. T he original image 
is displayed in the left-hand window, and the image that has 
passed through the flo is shown in theright-hand window. 
The goal of these test isto show that convertFromrGB -> 
ConvertTorGB iS lossless, 

-converttoindexpixel ConvertToIndex test, TripleBand BandByPixel. 


-converttoindexplane ConvertToIndex test, TripleBand BandByPlane. 
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-convertfromindex Thetest init function uses a flo containing convertToIndex to 
display an image in the left window. T he test function uses 
this drawable as input to a flo that does convertFromIndex -> 
ConvertToIndex and sends the resulting image to the right 
window. The result should be lossless. 

-complex A somewhat large flo that uses control planes, LUTs, Point, 
PasteUp, Logical, Constrain, Dither, Geometry, MatchHistogram, 
BandCombine, and BandSelect Aanents. See the Postscript file 
complex.ps for arendition of the photoflo that is executed. 


X DEFAULTS 
There are no X defaults used by this program. 


SEE ALSO 


X(1), xt1pert(1), x11perfcomp(1) 
BUGS 
There should be an maces environment variable to augment the - images option. 


M any tests only scratch the surface of possible test cases. Some of the options available for certain flo elements are either 
inadequately tested, or ignored altogether. T here are insufficient tests for bitonal, large pixel, or triple band tests. 


Some of the test names are inconsistently cased, for example, -Abort and -dithert. 
Sometests are hopelessly slow when run against machines with slow FPUs. 


Bitonal images are, for the most part, displayed using the ExportDrawable flo element; however, ExportDrawablePlane would 
bea better choice. 


AUTHOR 
Syd Logan (AGE Logic, Inc.) 
X Verson 11 Release 6 
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ximtoppm— Convert an x1m file into a portable pixmap 


SYNOPSIS 


ximtoppm [xi mfile] 


DESCRIPTION 


Reads an xim file as input. Produces a portable pixmap as output. The xim toolkit is included in the contrib tree of the 
X.V11R4 release 


SEE ALSO 
ppm(5) 


AUTHOR 
Copyright (c) 1991 by J ef Poskanzer. 


25 March 1990 
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xinetd— T he extended Internet services daemon 


SYNOPSIS 


xinetd [options ] 


DESCRIPTION 


xinetd performs the same function as ineta: it starts programs that provide Internet services. Instead of having such servers 
started at system initialization time, and be dormant until a connection request arrives, xinetd is the only daemon process 
started and it listens on all service ports for the services listed in its configuration file. When a request comes in, xinetd starts 
the appropriate server. Because of the way it operates, xinetd (aswell as inetd) is also referred to as a super-server. 


T he services listed in xinetd’s configuration file can be separated into two groups. Services in the first group are called 
multithreaded and they require the forking of a new server process for each new connection request. The new server then 
handles that connection. For such services, xinetd keeps listening for new requests so that it can spawn new servers. On the 
othe hand, the second group includes services for which the service daemon is responsible for handling all new connection 
requests. Such services are called single-threaded and xinetd will stop handling new requests for them until the server dies. 
Services in this group are usually datagram based. 


So far, the only reason for the existence of a super-server was to conserve system resources by avoiding to fork alot of 
processes who might be dormant for most of their lifetime. W hile fulfilling this function, xinetd takes advantage of the idea 
of a super-server to provide features such as access control and logging. Furthermore, xineta is not limited to services listed in 
/etc/services. | herefore, anybody can use xinetd to start special-purpose servers. 


OPTIONS 
-d Enables debug mode. T his produces alot of debugging 
output, and it makes it possible to use a debugger on xinetd. 
-syslog syslog facility This option enables syslog logging of xinetd-produced 


messages using the specified syslog facility. The following 
facility names are supported: daemon, auth, user, local[0-7] 
(check syslog.conf(5) for thar meanings). T his option is 
ineffective in debug mode because all relevant messages are 
sent to the teminal. 

-filelog logfile xinetd-produced messages will be placed in the specified file 
M essages are always appended to the file If the file does not 
exist, it will be created. T his option is ineffective in debug 
mode because all relevant messages are sent to the terminal. 


-f config file Determines the file that xinetd uses for configuration. T he 
default is /etc/xinetd.conf. 

-pid The process pid is written to standard error. This option is 
ineffective in debug mode 

-loop rate This option sets the loop rate beyond which a serviceis 


considered in error and is deactivated. T he loop rate is 
specified in terms of the number of servers per second that can 
be forked for a process. T he speed of your machine determines 
the correct value for this option. T he default rate is 10. 

-reuse If this option is used, xinetd will set the socket option 
SO_REUSEADDR before binding the service socket to an Internat 
address. T his allows binding of the address even if there are 
programs that useit, which happens when a previous instance 
of xineta has started some servers that are still running. This 
option hasno effect on RPC services. 
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-limit proc_limit This option places a limit on the number of concurrently 
running processes that can be started by xinetd. | ts purpose is 
to prevent process table overflows. 


-logprocs |i mit This option places a limit on the number of concurrently 
running servers for remote user ID acquisition. 

-shutdownprocs |i mit This option places a limit on the number of concurrently 
running servers for service shutdown (forked when the Record 
option is used). 





The syslog and filelog options are mutually exclusive. If noneis specified, the default is syslog using the daemon facility. 
You should not confuse xineta messages with messages related to service logging. T he latter are logged only if this is specified 
via the configuration file. 


CONFIGURATION FILE 


The configuration file determines the services provided by xineta. Any line whose first nonwhitespace character is a# is 
considered a comment line. Empty lines are ignored. 


The file contains entries of the form: 


service <service_name> 


{ 


<attribute> <assign_op><value><value> ... 


} 


Theassignment operator, assign_op, can be oneof =, +=, -=. The majority of attributes support only the simple assignment 
operator, =. Attributes whose value is a set of values support all assignment operators. For such attributes, += means adding a 
value to the set and -= meansremoving a value from the set. A list of these attributes is given after all the attributes are 
described. 


Each entry defines a serviceidentified by the service_name. T he following isa list of available attributes: 


id This attribute is used to uniquely identify aservice Thisis 
useful because there exist services that can use different 
protocols and need to be described with different entriesin the 
configuration file. By default, the service id is the sameas the 


service name. 
type Possible values are the following: 
RPC If this is an Rec service 
INTERNAL If this is a service provided by xineta. 
UNLISTED If this is a service not listed in /etc/services. 
flags Possible flag values are 
REUSE Set the so_rReuseappr flag on the service socket. 


INTERCEPT Intercept packets or accepted connections in 
order to verify that they are coming from 
acceotable locations (internal or multithreaded 
services cannot be intercepted). 


NORETRY Avoid retry attempts in case of fork failure. 
socket type Possible values are 

stream Stream-based service 

dgram D atagram-based service 

raw Service that requires direct access to IP 


seqpacket Service that requires reliable sequential 
datagram transmission 


protocol 


wait 


user 


group 


instances 


server 


server_args 


only_from 


no_access 
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Determines the protocol that is enployed by theservice The 
protocol must exit in /etc/protocols. If this attribute is not 
defined, the default protocol employed by the service will be 
used. 

This attribute determines if the service is single threaded or 
multithreaded. If its value is yes, the service is single threaded; 
this means that xinetd will start the server and then it will stop 
handling requests for the service until the server dies. If the 
attribute value is no, the service is multithreaded and xinetd 
will keep handling new service requests. 

D etermines the uid for the server process. T he username must 
exist in /etc/passwd. T his attribute is ineffective if the effective 
user 1D of xineta isnot super-user. 

Determines the gid for the server process. The group name 
must exist in /etc/group. If a group is not specified, the group 
of user will be used (from /etc/passwa). T his attribute is 
ineffective if the effective user ID of xinetd is not super-user. 
D etermines the number of servers that can be simultaneously 
active for a service. By default, there is no limit. T he value of 
this attribute can be either anumber or unLimiTeEp, which 
means that there is no limit. 

Determines the program to execute for this service 


D etermines the arguments passed to the server. In contrast to 
inetd, the server name should not be included in server_args. 


D etermines the remote hosts to which the particular serviceis 
available. | ts value is a list of |P addresses that can be specified 
in any combination of the following ways: 

a) A numeric address in the form of sd .%d .%d .%d. If the 
rightmost components are @, they are treated as wildcards 
(for example, 128.138.12.@ matches all hosts on the 
128.138.12 Subnet). 0.0.0.0 matchesall Internet addresses, 

b) A factorized address in the form of %d .%d .%d . {%d sd, 2.2} 
Thereis no need for all four components 
(%d .%d . {2d ,%d,.. .%d} IS also OK). H owever, the factorized 
part must be at the end of the address. 

c) A network name (from /etc/networks). 


d) A hostname. All IP addresses of the specified hostname will 
be used. 


Specifying this attribute without a value makes the service 
available to nobody. 


D etermines the remote hosts to which the particular serviceis 
unavailable Its value can be specified in the same way as the 
value of the only from attribute T hese two attributes 
determine the location access control enforced by xinetd. If 
none of the two is specified for a service, the service is available 
to anyone If both are specified for a service, the one that is the 
better match for the address of the remote host determines if 
the service is available to that host (for example, if the only 
from list contains 128.138.209.@ and theno access list contains 
128.138.209.10, then the host with the address 128.138.209.10 
can not access the service). 
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access times 


log_type 


log_on_success 


log_on_failure 


Determines the time intervals when the service is available An 

interval has the form hour: min- hour: min (Connections will be 

accepted at the bounds of an interval). H ours can range from 0 

to 23 and minutes from 0 to 59. 

Determines where the service log output is sent. There are two 

formats: 

SYSLOG syslog | Thelog output is sent to syslog at 

facility the specified facility. If aleve 

[syslog level] iS present, the messages will be recorded at 
that level instead of Log_1nFo (which isthe 


default level). 
FILE file The log output is appended to tile, 
[soft_limit which will be created if it does 
[hard_limit]] not exist. Two limits on the size of the log 


file can be optionally specified. The first 
limit isa soft one; xinetd will log a message 
the first time this limit is exceeded (if xinetd 
logs to syslog, the message will be sent at 
the Log_ALertT priority level). The second 
limit isa hard limit; xineta will stop logging 
for the affected service (if thelog fileisa 
common log file, then more than one service 
may be affected) and will log a message 
about this (if xinetd logs to syslog, the 
message will be sent at the Log_ALerT priority 
level). If ahard limit is not specified, it 
defaults to the soft limit increased by 1 
percent but the extra size must be within the 
parameters LoG_EXTRA_MIN and LOG_EXTRA_MAX 
(defined in config.h). 

Determines what information is logged when a server is started 

and when that server exits (the service!D is always included in 

the log entry). Any combination of the following values may 

be specified: 

PID Logs the server process ID . (If the serviceis 

implemented by xinetd without forking another 
process, the logged process 1D will bea.) 


HOST Logs the ranote host address 
TIME Logs the time when the server was started. 
USERID Logs the user ID of the remote user using the 


RFC 931 identification protocol. T his option is 
available only for multithreaded stream services. 
EXIT Logs the fact that a server exited along with the 
exit status or the termination signal (the process 
ID is also logged if the pp option is used). 
DURATION Logs the duration of a service session. 
Determines what information is logged when a server cannot 
be started (either because of a lack of resources or because of 
access control restrictions). The service!D is always included 
in thelog entry along with the reason for failure Any 
combination of the following values may be specified: 


HOST Logs the renote host address. 
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TIME Logs the time when the server was started. 

useRID Logs the user ID of theremote user using the RFC 
931 identification protocol. This option is available 
only for multithreaded stream services. 


ATTEMPT — Logs the fact that a failed attenpt was made 


recorD _—Recordsinformation from the remote end in case 
the server could not be started. This allows 
monitoring of attempts to use the service. For 
example, the login service logs the local user, 
remote user, and terminal type Currently, the 
services that support this option are logiun, shell, 
exec, finger 


rpc_version Determines the RPC version for an RPC service The version 
can bea single number or arangein the form number- 
number. 

env The value of this attribute is a list of strings of the form 


name=value. T hese strings will be added to the environment 
before starting a server (therefore the server's environment will 
include xinetd's environment plus the specified strings). 


passenv The value of this attribute is a list of environment variables 
from xineta’s environment that will be passed to the server. 
port Determines the service port. If this attribute is specified for a 


service listed in /etc/services, it must be equal to the port 
number listed in that file. 


You don’t need to specify all of the preceding attributes for each service. T he necessary attributes for a service are the 
following: 


socket type 


user (non-unlisted services only) 
server (non-internal services only) 

wait 

protocol (RPC and unlisted services only) 
rpc_version (RPC services only) 

port (unlisted services only) 


The following attributes support all assignment operators, except as indicated: 


only_from 

no_access 

log_on_success 

log_on_failure 

passenv 

env (does not support the -= operator) 


T hese attributes can also appear more than once in a service entry. The remaining attributes support only the= operator and 
can appear at most once in a service entry. 
The configuration file may also contain a single defaults entry that has the form: 


defaults 
{ 


<attribute> = <value><value> ... 


} 
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This entry provides default attribute values for service entries that don’t specify those attributes. Possible default attributes: 
log type 
log_on_success (cumulative effect) 
log_on failure (cumulative effect) 
only_from (cumulative effect) 
( ) 
( ) 


cumulative effect 








no_access 
passenv cumulative effect 
instances 

disabled (cumulative effect) 


Attributes with a cumulative effect can be specified multiple times with the values specified each time accumulating (in other 
words, = does the same thing as +=). With the exception of disabled they all have the same meaning as if they were specified 
in aservice entry. disabled determines services that are disabled even if they have entries in the configuration file This allows 
for quick reconfiguration by specifying disabled services with the disabled attribute instead of commenting them out. The 
value of this attribute isa list of syace-separated service ID s. 


INTERNAL SERVICES 


xinetd provides the following services internally (both stream- and datagram-based): echo, time, daytime, chargen, and 
discard. T hese services are under the same access restrictions as all other services except for the ones that don’t require xinetd 
to fork another process for them. T hose ones (time, daytime, and the datagram-based echo, chargen,and discard) haveno 
limitation in thenumber of instances. 


CONTROLLING xinetd 


xinetd performs certain actions when it receives certain signals. The actions associated with the specific signals can be 
redefined by editing config.h and recompiling. 


SIGUSR1 Causes a soft reconfiguration, which means that xineta rereads 
the configuration file and adjusts accordingly. 
SIGUSR2 Causes a hard reconfiguration, which is the same as a soft 


reconfiguration exceot that servers for services that areno 
longer available are terminated. Access control is performed 
again on running servers by checking the remote location, 
access times and server instances. If the number of server 
instances is lowered, some arbitrarily picked servers will be 
killed to satisfy the limit; this will happen after any servers are 
terminated because of failing the remote location or access 
time checks. Also, if the 1ntercepT flag was clear and is set, any 
running servers for that service will be terminated; the purpose 
of this is to ensure that after a hard reconfiguration there will 
be no running servers that can accept packets from addresses 
that do not meet the access control criteria. 





SIGQUIT Causes program termination. 

SIGTERM Terminates all running servers before terminating xinetd. 

SIGHUP Causes an internal state dump (the default dump file is /tmp/ 
xinetd.dump; to change the filename, edit config.h and 
recompile). 

SIGIOT Causes an internal consistency check to verify that the data 


structures used by the program havenot been corrupted. 
When the check is completed xinetd will generate a message 
that says if the check was successful or not. 


xinetd 


On reconfiguration, the log files are closed and reopened. T his allows removal of old log files. Also, the following attributes 
cannot be changed on reconfiguration: socket_type, wait, protocol, type. 


Xinetd LOG FORMAT 
Log entries are lines with the following format: 


entry: service-id data 


The data depends on the entry. Possible entry types: 


START Generated when a server is started 

EXIT Generated when aserver exits 

FAIL Generated when it is not possible to start a server 

DATA Generated when an attenpt to start a server fails and the 
service supports the recorb log option. 

USERID Generated if the usertp log option is used. 


In the following formats, the information enclosed in brackets appears if the appropriate log option is used. 

A start entry has the format 

START: service-id [pid=%d] [from=%d.%d.%d.%d] [time=ti me ] 

Timeis given as year/month/day@hour:minutes:seconds 

An exit entry has the format 

EXIT: service-id [type=%d] [pid=%d] [duration=%d(sec) ] 

typecan be either status or signal. Thenumbe is eithe the exit status or the signal that caused process termination. 
A FAIL entry has the format: 

FAIL: service-id reason [from=%d.%d.%d.%d] [time=ti me ] 

Possible reasons are 


fork A certain number of consecutive fork attempts failed (this 
number is a configurable parameter). 


time 
address 


service_limit 


process_limit 


A pata entry has the format 
DATA: service-id data 


Thedata logged depends on the sevice. 


login 


exec 


Thetimecheck failed. 
The address check failed. 


The allowed number of server instances for this service would 
be exceeded. 


A limit on thenumber of forked processes was specified and it 
would be exceeded. 


remote_user=%s local_user=%s tty=%s 


remote_user=%s verify=status command=% s Possible status 
values: 


ok The password was correct 

failed The password was incorrect 

baduser No such user 

shell renote_user=%s local_ user=%s command=%s 
finger received string OF EMPTY-LINE 
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A usertp entry has the format 
USERID: text 


Thetext istheresponse of theRFC 931 daemon at the ranote end excluding the port numbers (which are included in the 
response). H ere’s an example 


# 

# Sample configuration file for xinetd 

# 

defaults 

{ 
log_type = FILE /var/log/servicelog 
log_on_success = PID 
log_on_failure = HOST TIME RECORD 
only_from = 128.138.193.0 128.138.204.0 128.138.209.0 
only from = 128.138.252.1 
instances = 10 
disabled = rstatd 

} 

# 


# Note 1: the protocol attribute is not required 
# Note 2: the instances attribute overrides the default 


# 
service login 
{ 
socket_type = stream 
protocol = tcp 
wait = no 
user = root 
server = /usr/etc/in.rlogind 
instances = UNLIMITED 
} 
# 


# Note 1: the instances attribute overrides the default 
# Note 2: the log on success flags are augmented 


# 
service shell 
{ 
socket_type = stream 
wait = no 
user = root 
instances = UNLIMITED 
server = /usr/etc/in.rshd 
log_on_success += HOST TIME RECORD 
} 
service ftp 
{ 
socket_type = stream 
wait = no 
user = root 
server = /usr/etc/in.ftpd 
server_args = -l 
instances = 4 
log_on_success += DURATION HOST USERID 
access_times = 2:00-9:00 12:00-24:00 
} 
# 


# This entry and the next one specify internal services. Since this 

# is the same service using a different socket type, the id attribute 
# is used to uniquely identify each entry 

# 


xinit 


service echo 


{ 
id = echo-stream 
type = INTERNAL 
socket_type = stream 
user = root 
wait = no 

} 

service echo 

{ 
id = echo-dgram 
type = INTERNAL 
socket_type = dgram 
user = root 
wait = no 

} 

# 

# Sample RPC service 

# 


service rstatd 


type = RPC 

socket_type = dgram 

protocol = udp 

server = /usr/etc/rpc.rstatd 

wait = yes 

user = root 

rpc_version = 2-4 

env = LD_LIBRARY_PATH=/etc/securelib 


} 
# 


# Sample unlisted service 

# 

service unlisted 

{ 
type = UNLISTED 
socket_type = stream 
protocol = tcp 
wait = no 
server = /home/user/some server 
port = 20020 

} 

FILES 


/etc/xinetd. conf D efault configuration file 
/tmp/xinetd. dump D efault dump file 


SEE ALSO 
ineta(8) 
Postel J., Echo Protocol, RFC 862, M ay 1983. 
Postel J., Discard Protocol, RFC 863, M ay 1983. 
Postel J., Character Generator Protocol , RFC 864, M ay 1983. 
Postel J., Daytime Protocol, RFC 867, M ay 1983. 
Postel J., H arrenstien K., TimeProtocol, RFC 868, M ay 1983. 
St. Johns M ., Authentication Server, RFC 931, January 1985. 
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AUTHOR 
Panos T sirigotis (CS D epartment, University of Colorado, Boulder) 


NOTES 


When theattributes only_from and no_access are not specified for a service (eather directly or via defaults), the address check 
is considered successful (that is, access will not be denied). 


If the userrD log option is specified and the ranote RFC 931 server sends back an error reply, access will not be denied. 
If the userrD log option is specified and the renote host does not run an RFC 931 server, there will be no indication in the 
log of that fact (other than the missing usertp log entry). 
BUGS 
Supplementary group IDs are not supported. 


If the 1nTERcEPT flag is not used, access control on the address of the remote host is not performed when wait is yes and 
socket_type IS stream. 


If the 1nTERcEPT flag is not used, access control on the address of the remote host for services where wait is yes and 
socket_type iS dgram is performed only on the first packet. The server may then accept packets from hosts not in the access 
control list. This can happen with RPC services. 


Unlisted RPC services are not supported; that is, all RPC services must be registered in /etc/rpc. Specifying an RPC service 
by itsRPC program number isnot (yet) possible. 


There is no way to put a space in an environment variable. 
When wait iS yes and socket_type iS stream, thesocket passed to the server can only accept connections. 
The intercept flag is not supported for internal services or multithreaded services. 


Interception works by forking a process that acts as a filter between the remote host(s) and the local server. This obviously 
has a pa'formanceimpact which depends on the volume of information exchanged. It is up to you to make the compromise 
between security and performance for each service. 


PRONUNCIATION 


xinetd iS pronounced “zy-net-d.” 
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Xinit 
xinit— X Window System initializer 
SYNOPSIS 
xinit [[client ] options ][-- [ server ][display ] options ] 
DESCRIPTION 


The xinit program is used to start the X Window System server and a first client program on systems that cannot start X 
directly from /etc/init or in environments that use multiple window systens. When this first client exits, xinit will kill the 
X server and then terminate. 


If no specific client program is given on the command line, xinit will look for a filein the user’s home directory called 
.xinitre to run as a shell script to start up client programs. If no such file exists, xinit will use the following as a default: 


xterm -geometry +1+1 -n login -display :0 


xinit 


If no specific server program is given on the command line, xinit will look for a filein the user’s home directory called 
.xserverre to run aSa shal script to start up the server. If no such file exists, xinit will use the following as a default: 


X 30 


N ote that this assumes that there is a program named X in the current search path. H owever, servers are usually named 
Xdisplaytype where displaytype is the type of graphics display that is driven by this server. T he site administrator should, 
therefore, make a link to the appropriate type of server on the machine or create a shell script that runs xinit with the 
appropriate server. 


N ote, when using a .xserverrc script be sure to mark the real X server aS exec. Failing to do this can make the X server slow 
to start and exit. For example 


exec Xdisplaytype 


An important point is that programs which are run by xinitre should be run in the background if they do not exit right 
away, so that they don’t prevent other programs from starting up. H oweve,, the last long-lived program started (usually a 
window manager or terminal enulator) should be left in the foreground so that the script won’t exit (which indicates that 
the user is done and that xinit should exit). 


An alternate client and/or server may be specified on the command line. T he desired client program and its arguments 
should be given as the first command-line arguments to xinit.T 0 specify a particular server command line, append two 
dashes (--) to the xinit command line (after any client and arguments) followed by the desired server command. 


Both theclient program name and the server program name must begin with a slash (/) or a period (.). Otherwise they are 
treated as arguments to be appended to their respective startup lines. This makes it possible to add arguments (for example 
foreground and background colors) without having to retype the whole command line 


If an explicit server name isnot given and the first argument following the double dash (--) isa colon followed by a digit, 
xinit will use that number as the display number instead of zero. All remaining arguments are appended to the server 
command line 


EXAMPLES 
Following are several examples of how command-line arguments in xinit are used: 


This will start up a server named X and run the user's xinitrc, if it exists, or else start an xterm: 
xini 


2 


This is how one could start a specific type of server on an alternate display: 
xinit -- /usr/X11R6/bin/Xqdss :1 


This will start up a server named X, and will append the given arguments to the default xterm command (it will ignore 
xinitrc): 


xinit -geometry =80x65+10+10 -fn 8x13 -j -fg white -bg navy 


This will usethe command xsun -1 -c to start the server and will append the arguments -e widgets to the default xterm 
command: 


xinit -e widgets -- ./Xsun -1 -c 











This will start a server named X on display 1 with the arguments -a 2 -t5: 
xinit /usr/ucb/rsh fasthost cpupig -display ws:1 -- :1 -a 2 -t 5 





It will then start a remote shal on the machine fasthost in which it will run the command cpupig, telling it to display back on 
the local workstation. 

Following is a sample xinitre that starts a clock, starts several terminals, and leaves the window manage running as the 
“last” application. Assuming that the window manager has been configured properly, the user then chooses the Exit menu 
item to shut down X. 





xrdb -load $HOME/.Xresources 
xsetroot -solid gray & 
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xclock -g 50x50-0+0 -bw @ & 
xload -g 50x50-50+0 -bw @ & 
xterm -g 80x24+0+0 & 

xterm -g 80x24+0-0 & 

twm 


Sites that want to create a common startup environment could simply create a default xinitre that references a sitewide 
startup file: 


#!/bin/sh 
. /usr/local/lib/site.xinitre 


Another approach is to write a script that starts xinit with a specific shal script. Such scripts are usually named x11, xstart, 
Or startx, and are a convenient way to provide a simple interface for novice users: 


#!/bin/sh 
xinit /usr/local/lib/site.xinitre -- /usr/X11R6/bin/X bc 
ENVIRONMENT VARIABLES 

DISPLAY This variable gets set to thename of the display to which 
clients should connect. 

XINITRC This variable specifies an init file containing shell commands 
to start up theinitial windows. By default, xinitrc in the 
homedirectory will be used. 

FILES 

.xinitre Default client script 

xterm Client to run if .xinitre does not exist 

.xserverrc D efault server script 

x Server to run if .xserverrc does not exist 

SEE ALSO 
X(1), startx(1), xserver(1), xterm(1) 
AUTHOR 


Bob Schafler (MIT Laboratory for Computer Science) 
X Version 11 Release 6 


xkill 


xkill— Kill a client by its X resource 


SYNOPSIS 


xkill [-display displ ayname] [-id resource] [-button number] [-frame] [-al1l] 


DESCRIPTION 


xkill isa utility for forcing theX server to close connections to clients. T his program is very dangerous, but is useful for 
aborting programs that have displayed undesired windows on auser’s screen. If no resource identifier is given with -id, xkill 
will display a special cursor as a prompt for the user to select a window to be killed. If a pointer button is pressed over a 
nonroot window, the server will close its connection to the client that created the window. 
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OPTIONS 

-display displ ayname This option specifies the name of the X server to contact. 

-id resource This option specifies the X identifier for the resource whose 
creator is to be aborted. If no resource is specified, xki11 will 
display a special cursor with which you should select a window 
to be kill. 

-button number This option specifies the number of pointer button that should 


be used in sdecting a window to kill. If the word “any” is 
specified, any button on the pointer may be used. By default, 
the first button in the pointer map (which is usually the 
leftmost button) is used. 

-all This option indicates that all clients with top-level windows on 
the screen should be killed. xki11 will ask you to select the root 
window with each of the currently defined buttons to give you 
several chances to abort. U se of this option is highly discour- 
aged. 

-frame This option indicates that xki11 should ignore the standard 
conventions for finding top-level client windows (which are 
typically nested inside a window manager window), and 
simply believe that you want to kill direct children of the root. 


XDEFAULTS 
Button Specifies a specific pointer button number or the word “any” 
to use when selecting windows. 
SEE ALSO 


X(1), xwininfo(1), XKillClient and xGetPointerMapping in the Xlib ProgrammersM anual, Killclient in the X Protocol 
Sped fication 


AUTHOR 
Jim Fulton (MIT X Consortium) and D ana Chee (Bellcore) 
X Version 11 Release 6 


xlogo 
xlogo— X Window System logo 


SYNOPSIS 


xlogo [-toolkitoption ...] 


DESCRIPTION 
The xlogo program displays the X Window System logo. 


OPTIONS 


Xlogo accepts all of the standard X Toolkit command-line options, as well as the following: 


-shape This option indicates that the logo window should be shaped 
rather than rectangular. 
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RESOURCES 


The default width and the default haght are each 100 pixels. This program uses the Logo widget in the Athena widget set. It 

understands all of the Simple widget resource names and classes as well as: 

foreground (class Foreground) Specifies the color for the logo. The default depends on 
whether reverseVideo is specified. If reverseVideo is specified, 
the default is xtDefaultForeground, otherwise the default is 
XtDefaultBackground. 


shapeWindow (class ShapeWindow) Specifies that the window is shaped to the X logo. T he default 
iS False. 


WIDGETS 


In order to specify resources, it is useful to Know the hierarchy of the widgets that compose x1ogo.!n the following notation, 
indentation indicates hierarchical structure. The widget class nameis given first, followed by the widget instance name. 


XLogo xlogo 


Logo xlogo 
ENVIRONMENT 
DISPLAY To get the default host and display number. 
XENVIRONMENT To get thename of a resource file that overrides the global 
resources stored in the RESOURCE_MANAGER propetty. 
FILES 
<XRoot>/1ib/X11/app-defaults/XLogo Specifies required resources 
SEE ALSO 
X(1), xrdb(1) 
AUTHORS 


Ollie} ones of Apollo Computer and Jim Fulton of theM IT X Consortium wrote the logo graphics routine, based on a 
graphic design by D anny Chong and Ross Chapman of Apollo C omputer. 
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xlsatoms 


xlsatoms— List interned atoms defined on server 


SYNOPSIS 


xlsatoms [-options ...] 


DESCRIPTION 


xlsatoms lists the interned atoms. By default, all atoms starting from 1 (the lowest atom value defined by the protocol) are 
listed until unknown atom is found. If an explicit range is given, x1satoms will try all atoms in the range, regardless of 
whether or not any are undefined. 


xIsclients 


OPTIONS 
-display dpy This option specifies the X server to which to connect. 
-format string This option specifies a printf-style string used to list each 


atom <value, name> pair, printed in that order (value isan 
unsigned long and name iSachar *). xlsatoms will supply a 
newline at the end of each line The default is %1d\t%s. 


-range [low]-[high] This option specifies the range of atom values to check. If! ow 
isnot given, a value of 1 is assumed. If hi gh isnot given, 
xlsatoms will stop at the first undefined atom at or above! ow. 


-name string This option specifies the name of an atom to list. If the atom 
does not exist, a message will be printed on thestandard error. 


SEE ALSO 
x(1), Xserver(1), xprop(1) 
ENVIRONMENT 
DISPLAY To get the default host and display to use 
AUTHOR 
Jim Fulton (MIT X Consortium) 
X Version 11 Release 6 


xlsclients 


xlsclients— List client applications running on a display 


SYNOPSIS 


xlsclients [-display displayname] [-a] [-1] [-m maxcmdlen] 


DESCRIPTION 


xlsclients iSa utility for listing information about theclient applications running on adisplay. It may be used to generate 
scripts representing a snapshot of the user’s current session. 


OPTIONS 

-display displ ayname This option specifies the X server to contact. 

-a This option indicates that clients on all screens should be 
listed. By default, only those clients on the default screen are 
listed. 

-1 List in long format, giving the window name, icon name, and 


class hints in addition to the machinename and command 
string shown in the default format. 


-m maxcmdlen This option specifies the maximum number of characters in a 
command to print out. The default is 10000. 


ENVIRONMENT 


DISPLAY To get the default host, display number, and screen. 
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SEE ALSO 


x(1), xwininfo(1), xprop(1) 


AUTHOR 
Jim Fulton (MIT X Consortium) 


xlsfonts 

xlsfonts— Server font list displayer for X 
SYNOPSIS 

xlsfonts [-options ...] [-fn pattern] 
DESCRIPTION 


X Verdon 11 Reease 6 


xlsfonts lists the fonts that match the given pattern. The wildcard character « may be used to match any sequence of 
characters (including none), and 2 to match any single character. If no pattern is given, * is assumed. 


The* and 2 characters must be quoted to prevent them from being expanded by the shell. 











OPTIONS 

-display host: dpy This option specifies the X server to contact. 

-1 Lists some attributes of the font on one line in addition to its 
name 

-11 Lists font propertiesin addition to -I output. 

-111 Lists character metrics in addition to -11 output. 

=m This option indicates that long listings should also print the 
minimum and maximum bounds of each font. 

-C This option indicates that listings should use multiple 
columns. T hisis the same as -n @. 

-1 This option indicates that listings should use a single column. 
This is the same as -n 1. 

-w width This option specifies the width in characters that should be 
used in figuring out how many columns to print. The default 
iS 79. 

-n columns This option specifies the number of columns to use in 
displaying the output. By default, it will attempt to fit as many 
columns of font names into the number of character specified 
by -w width. 

-u This option indicates that the output should be left unsorted. 

-0 This option indicates that x1stonts should do an openFont 
(and queryFont, if appropriate) rather than a ListFonts. T hisis 
useful if ListFonts OF ListFontsWithInfo fail to list aknown 
font (as is the case with some scaled font systems). 

-fn pattern This option specifies the font name pattern to match. 

SEE ALSO 


x(1), Xserver(1), xset(1), xfa(1), X Logical Font D escription Conventions 
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ENVIRONMENT 
DISPLAY To get the default host and display to use 


BUGS 


Doing xlsfonts -1 can tieup your server for a very long time. T hisis really a bug with single-threaded nonpreemptable 
servers, not with this program. 


AUTHOR 
M ark Lillibridge (MIT Project Athena), Jim Fulton (MIT X Consortium), and Phil Karlton (SGI) 
X Version 11 Release 6 


xmag 


xmag— M agnify parts of the screen 


SYNOPSIS 


xmag [ -mag magfactor ][-source geom ][-toolkitoption ...] 


DESCRIPTION 


The xmag program allows you to magnify portions of an X screen. If no explicit region is specified, a square with the pointer 
in the upper-left corner is displayed indicating the area to be enlarged. T he area can be dragged out to the desired size by 
pressing Button 2. After a region has been selected, a window is popped up showing a blown-up version of the region in 
which each pixel in the source image is represented by asmall square of the same color. Pressing Button 1 in the enlargement 
window shows the position and RGB value of the pixd under the pointer until the button isreleased. Typinga or *C in the 
enlargement window exits the program. The application has five buttons across its top. Close ddetes this particular 
magnification instance. Replace brings up the rubber band sdector again to sdect another region for this magnification 
instance. N ew brings up the rubber band sdector to create a new magnification instance Cut puts the magnification image 
into the primary selection. Paste copies the primary selection buffer into xmag. N ote that you can cut and paste between xmag 
and the bitmap program. Resizing xmag resizes the magnification area. xmag preserves the colormap, visual, and window depth 
of the source 


WIDGETS 


xmag uses the X Toolkit and the Athena W idget Set. The magnified image is displayed in the Scale widget. For more 
information, see the Athena W idget Set documentation. Following is the widget structure of the xmag application. Indenta- 
tion indicates hierarchical structure. T he widget class name is given first, followed by the widget instance name. 


Xmag xmag 
RootWindow root 
TopLevelShell xmag 
Paned pane1 
Paned pane2 
Command close 
Command replace 
Command new 
Command select 
Command paste 
Label xmag label 
Paned pane2 
Scale scale 
OverrideShell pixShell 
Label pixLabel 
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OPTIONS 


-source geom 


-mag integer 


AUTHORS 
D ave Sternlicht and Davor M atic (MIT X Consortium) 


xmkmtf 


xmkmf— Create a Makefile from an Imakefile 


SYNOPSIS 


xmkmf [-a][topdir [ curdir ]] 


DESCRIPTION 


This option specifies the size and/or location of the source 
region on the screen. By default, a64x64 square is provided 
for the user to sdect an area of the screen. 

This option indicates the magnification to be used. The 
default iss. 
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The xmkmf command is the normal way to create a Makefile from an Imakefile shipped with third-party software. 


W hen invoked with no arguments in a directory containing an Imakefile, the imake program isrun with arguments 
appropriate for your systen (configured into xmkmf when X was built) and generates a Makefile. 


W hen invoked with the -a option, xmkmf builds the Makefile in thecurrent directory, and then automatically executes make 
Makefiles (in casethere are subdirectories), make includes, and make depend for you. Thisisthenormal way to configure 


software that is outside the X Consortium build tree. 


If working inside the X Consortium build tree (unlikely unless you are an X developer, and even then this option is never 
really used), the topdir argument should be specified as the relative pathname from the current directory to the top of the 
build tree Optionally, curdir may be specified asa relative pathname from the top of the build tree to the current directory. 
It isnecessary to supply curdir if the current directory has subdirectories, or the Makefile will not be able to build the 
subdirectories. If a topdir is given, xmkmf assumes nothing is installed on your system and looks for files in the build tree 


instead of using the installed versions. 


SEE ALSO 


imake(1) 


xmodmap 


xmodmap— Utility for modifying keymaps in X 


SYNOPSIS 
xmodmap [-options ...] [filename] 
DESCRIPTION 
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The xmodmap program is used to edit and display the keyboard modifier map and keymap table that are used by client 
applications to convert event keycodes into keysyms. It is usually run from the user’s session startup script to configure the 


keyboard according to personal tastes. 
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OPTIONS 
The following options may be used with xmodmap: 
-display display This option specifies the host and display to use 
-help This option indicates that a brief description of the command- 


line arguments should be printed on the standard error 
channel. T his will be done whenever an unhandled argument 
iS given to xmodmap. 

-grammar This option indicates that a help message describing the 
expression grammar used in files and with -e expressions 
should be printed on the standard error. 





-verbose This option indicates that xmodmap should print logging 
information asit parses its input. 

-quiet This option turns off the verbose logging. T hisis the default. 

-n This option indicates that xmodmap should not change the 


mappings, but should display what it would do, like make(1) 
does when given this option. 











-e expression This option specifies an expression to be executed. Any 
number of expressions may be specified from the command 
line 

-pm This option indicates that the current modifier map should be 
printed on the standard output. 

-pk This option indicates that the current keymap table should be 
printed on the standard output. 

-pke This option indicates that the current keymap table should be 
printed on the standard output in the form of expressions that 
can be fed back to xmodmap. 

-pp This option indicates that the current pointer map should be 








printed on the standard output. 


A lone dash means that the standard input should be used as 
the input file 





The filename specifies a file containing xmodmap expressions to be executed. This file is usually kept in the user’s home 
directory with aname like .xmodmaprc. 


EXPRESSION GRAMMAR 


The xmodmap program reads a list of expressions and parses them all before attempting to execute any of them. T his makes it 
possible to refer to keysyms that are being redefined in a natural way without having to worry as much about name conflicts. 


keycode NUMBER = KEYSYMNAME ... The list of keysyms is assigned to the indicated keycode (which 
may be specified in decimal, hex, or octal and can be 
determined by running the xev program. 

keycode any = KEYSYMNAME ... If no existing key has the specified list of keysyms assigned to 
it, aspare key on the keyboard is selected and the keysyms are 
assigned to it. The list of keysyms may be specified in decimal, 
hex, or octal. 

keysym KEYSYMNAME = KEYSYMNAME ... ThexkeysymName on the left sideis translated into matching 
keycodes used to perform the corresponding set of keycode 
expressions. T he list of keysym names may be found in the 
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header file <x11/keysymdef .h (without the xk_prefix) or the 
keysym database <xRoot>/1ib/X11/XKeysymDB, where <xRoot> 
refersto the root of the X11 install tree. N ote that if the same 
keysym is bound to multiple keys, the expression is executed 
for each matching keycode. 

clear MODI Fl ERNAME This removes all entries in the modifier map for the given 
modifier, where valid names are shift, Lock, Control, Modt, 
Mod2, Mod3, Mod4, and Mods (case does not matter in modifier 
names, although it does matter for all other names). For 
example, clear Lock will remove any keys that were bound to 
the shift lock modifier. 

add MODIFIERNAME = KEYSYMNAME ... This adds all keys containing the given keysyms to the 
indicated modifier map. The keysym names are evaluated after 
all input expressions are read to make it easy to write 
expressions to swap keys. (See the “Examples” subsection). 

remove MODIFIERNAME = KEYSYMNAME ... This removes all keys containing the given keysyms from the 
indicated modifier map. Unlike ada, the keysym names are 
evaluated as the line is read in. This allows you to remove keys 
from amodifier without having to worry about whether or not 
they have been reassigned. 





pointer =default This sets the pointer map back to its default settings (button 1 
generates a code of 1, button 2 generates a 2, and so on). 
pointer = NUMBER ... This sets to pointer map to contain the indicated button 


codes. T he list always starts with the first physical button. 


Lines that begin with an exclamation point (!) are taken as comments. 
If you want to change the binding of a modifier key, you must also remove it from the appropriate modifier map. 


EXAMPLES 


M any pointers are designed such that the first button is pressed using the index finger of the right hand. People who are left- 
handed frequently find that it is more comfortable to reverse the button codes that are generated so that the primary button 
is pressed using the index finger of the left hand. This could bedone on a3 button pointer as follows: % xmodmap -e "pointer 
=32 1", 


M any applications support the notion of M eta keys (similar to Control keys except that M eta isheld down instead of 
Control). H owever, some servers do not havea M eta keysym in the default keymap table so one neads to be added by hand. 
The following command will attach M eta to the M ultilanguage key (sometimes labeled C ompose Character). It also takes 
advantage of the fact that applications that need a M eta key simply need to get the keycode and don’t require the keysym to 
bein the first column of the keymap table This means that applications that are looking for a M ulti key (including the 
default modifier map) won't notice any change Example 


% xmodmap -e "keysym Multi_key = Multi_key Meta_L" 
Similarly, some keyboards have an Alt key but no M eta Key. In that case the following may be useful: 


2 


% xmodmap -e "keysym Alt L = Meta L Alt L" 


Oneof the moresimple yet convenient, uses of xmodmap is to set the keyboard's “rubout” key to generate an alternate 
keysym. This frequently involves exchanging Backspace with D elete to be more comfortable to the user. If the ttyModes 
resource in xterm is set as well, all terminal enulator windows will use the same Key for erasing characters: 


% xmodmap -e "keysym BackSpace = Delete" 
% echo "XTerm*ttyModes: erase *?" | xrdb -merge 
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Some keyboards do not automatically generate less than and greater than characters when the comma and period keys are 
shifted. This can be renedied with xmodmap by resetting the bindings for the commaand period with the following scripts: 
! 

! make shift-, be $<$ and shift-. be $>$ 

! 

keysym comma = comma less 

keysym period = period greater 


Oneof the more irritating differences between keyboards is the location of the C ontrol and Shift Lock keys. A common use 
Of xmodmap is to swap these two keys as follows: 
! 

! Swap Caps_Lock and Control_L 

! 

remove Lock = Caps_Lock 

remove Control = Control_L 

keysym Control_L = Caps_Lock 

keysym Caps_Lock = Control_L 

add Lock = Caps_Lock 

add Control = Control_L 


The keycode command is useful for assigning the same keysym to multiple keycodes. Although unportable it also makes it 
possible to write scripts that can reset the keyboard to a known state. T he following script sets the Backspace key to generate 
D elete (as shown earlier), flushes all existing caps lock bindings, makes the Caps Lock key bea control key, make F5 generate 
Escape, and makes Break/R eset be a shift lock. 


On the HP, the following keycodes have key caps as listed: 


! 

! 

! 

! 101 Backspace 

! 55 Caps 

! 14 Ctrl 

! 15 Break/Reset 
! 86 Stop 

! 89F5 

! 

keycode 101 = Delete 
keycode 55 = Control_R 


clear Lock 

add Control = Control_R 

keycode 89 = Escape 

keycode 15 = Caps_Lock 

add Lock = Caps_Lock 
ENVIRONMENT 

DISPLAY To get default host and display number 
SEE ALSO 

x(1), xev(1), x1ib documentation on key and pointer events 
BUGS 


Every time a keycode expression is evaluated, the server generates a MappingNotify event on every client. This can cause some 
thrashing. All of the changes should be batched together and done at once. Clients that recave keyboard input and ignore 
MappingNotify events will not notice any changes made to keyboard mappings. 


xmodmap should generate add and remove expressions automatically whenever a keycode that is already bound to amodifie is 
changed. 
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There should bea way to have the remove expression accept keycodes as wall as keysyms for those times when you really mess 


up your mappings. 


AUTHOR 


Jim Fulton (MIT X Consortium), rewritten from an earlier version by D avid Rosenthal (Sun M icrosystens) 


xon 


xon— Start an X program on aremote machine 


SYNOPSIS 
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xon remote-host [-access] [-debug] [-name window-name] [-nols] [-screen screen-no] [-user user-name] [command ...] 


DESCRIPTION 


xon runs the specified command (default xterm -1s) on the remote machine using rsh, remsh, OF rcmd. xon passes the DISPLAY, 
XAUTHORITY, aNd XUSERFILESEARCHPATH environment variables to the remote command. 


W hen no command is specified, xon runs xterm -1s. It additionally specifies the application name to be xterm-remote -host 


and the window title to be -fIremote-host. 


xon can only work when the remote host will allow you to log in without a password, by having an entry in the .rhosts file 


permitting access. 


OPTIONS 


N ote that the options follow the renote hostname (as they do with riogin). 


-access 


-debug 


-name window-name 
-nols 
-screen screen-no 


-user user-name 


BUGS 


Runs xhost locally to add the remote host to the host access list 
in the X server. This won't work unless xhost is given 
permission to modify the access list. 

Normally, xon disconnects the remote process from stdin, 
stdout, and stderr to eliminate the daemon processes that 
usually connect them across the network. Specifying the -debug 
option leaves than connected so that error messages from the 
remote execution are sent back to the originating host. 

This specifies a different application name and window title 
for the default command (xterm). 

N ormally xon passes the -1s option to the renote xterm; this 
option suspends that behavior. 

This changes the screen number of the p1sPLay variable passed 
to the renote command. 

By default, xon simply uses rsh/remsh/remd to connect to the 
remote machine using the same username as on the local 
machine. T his option causes xon to specify an alternative 
username. T his will not work unless you have authorization to 
access the remote account, by placing an appropriate entry in 
the remote user’s . hosts file. 


xon can get easily confused when the remote host, username, or various environment variable values contain whitespace 


xon has no way to send the appropriate X authorization information to the remote host. 
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xpmtoppm 


xpmtoppm— Convert an X11 pixmap into a portable pixmap 


SYNOPSIS 

xpmtoppm [xpmfile] 
DESCRIPTION 

Reads an X11 pixmap (XPM version 1 or 3) asinput. Produces a portable pixmap as output. 
KNOWN BUGS 


The support to XPM version 3 is limited. Comments can only be single lines and there must be for every pixd a default 
color name for acolor type visual. 
SEE ALSO 


ppmtoxpm(1), ppm(5) 
XPM M anual by Arnaud LeH ors (1ehors@mirsa. inria.fr) 


AUTHOR 
Copyright (c) 1991 by J ef Poskanzer. 
Upgraded to support XPM version 3 by Arnaud LeH ors (1ehors@mirsa. inria.fr) 9 April 1991 
16 August 1990 


Xprop 


xprop— Property displayer for X 
SYNOPSIS 


xprop [-help] [-grammar] [-id id] [-root] [-name name] [-frame] [-font font] 
[-display display] [-len n] [-notype] [-fs file] [-remove property-name ] 
[-spy] [-f atom format [dformat]]* [format [dformat] atom]* 


SUMMARY 
The xprop utility is for displaying window and font properties in an X server. One window or font is selected using the 
command-line arguments or possibly in the case of a window, by clicking on the desired window. A list of properties is then 
given, possibly with formatting information. 


OPTIONS 

-help Print out a summary of command-line options. 

-grammar Print out a detailed grammar for all command-line options. 

-id id This argument allows the user to select window id on the 
command line rather than using the pointer to select the target 
window. T his is very useful in debugging X applications where 
the target window is not mapped to the screen or where the 
use of the pointer might be impossible or interfere with the 
application. 

-name name This argument allows the user to specify that the window 


named name is the target window on the command line rather 
than using the pointer to sdect the target window. 


678 Part |: User Commands 


-font font This argument allows the user to specify that the properties of 
font font should be displayed. 

-root This argument specifies that X's root window is the target 
window. T his is useful in situations where the root window is 
completely obscured. 

-display display This argument allows you to specify the server to connect to; 
see x(1), 

-len n Specifies that at most, n bytes of any property should be read 
or displayed. 

-notype Specifies that the type of each property should not be 
displayed. 

-fs file Specifies that file fi |e should be used asa source of more 
formats for properties. 

-frame Specifies that when selecting a window by hand (that is, if 


nather -name, -root, nor -id iS given), look at the window 
manager frame (if any) instead of looking for the client 


window. 
-remove property- name Specifies the name of a property to be renoved from the 
indicated window. 
-spy Examine window propeties forever, looking for property 
change events. 
-f name format [dformat ] Specifies that the format for name should bef ormat and that 


the dformat for name should be df or mat. If dformat is missing, 
"= $0+\n" iS assumed. 


DESCRIPTION 


For each of these properties, its value on the selected window or font is printed using the supplied formatting information, if 
any. If no formatting information is supplied, internal defaults are used. If aproperty is not defined on the selected window 
or font, not defined is printed asthe value for that property. If no property list is given, all the properties possessed by the 
selected window or font are printed. 


A window may be selected in one of four ways. First, if the desired window isthe root window, the -root argument may be 
used. If the desired window is not the root window, it may be selected in two ways on the command line, eather by id 
number, such as might be obtained from xwininfo, or by name if the window possesses a name The -id argument selects a 
window by id number in either decimal or hex (must start with ox) while the -name argument selects a window by name. 


The last way to select a window does not involve the command line at all. If none of -font, -id, -name, and -root are 
specified, a crosshairs cursor is displayed and the user is allowed to choose any visible window by pressing any pointer button 
in the desired window. If it is desired to display properties of a font as opposed to a window, the -font argument must be 
used. 


O ther than the preceding four arguments and the -he1lp argument for obtaining help, and the -grammar argument for listing 
the full grammar for the command line, all the other command-line arguments are used in specifying both the format of the 
properties to be displayed and how to display than. The -1en n argument specifies that at most, n bytes of any given 
property will be read and displayed. This is useful, for example, when displaying the cut buffer on the root window, which 
could run to several pages if displayed in full. 


Normally, each property nameis displayed by printing first the property name then its type (if it has one) in parentheses, 
followed by its value. The -notype argument specifies that property types should not be displayed. The -#s argument is used 
to specify a file containing a list of formats for properties, whilethe -+ argument is used to specify the format for one 
property. 
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The formatting information for a property actually consists of two parts, a format and a dformat. T he format specifies the 
actual formatting of the property (that is, is it made up of words, bytes, or longs?, and so on) while the dformat specifies how 
the property should be displayed. 


The following paragraphs describe how to construct formats and dformats. H owever, for the vast majority of users and uses, 
this should not be necessary as the built-in defaults contain the formats and dformats necessary to display all the standard 
properties. It should only be necessary to specify formats and dformats if anew propetty is being dealt with or the user 
dislikes the standard display format. N ew users especially are encouraged to skip this part. 


A format consists of ao, 8, 16, or 32 followed by a sequence of one or more format characters. Thea, 8, 16, or 32 specifies 
how many bits per field there are in the property. 


Zero is a special case that means use the field size information associated with the property itself. (T hisis only needed for 
special cases like type 1nTEGeER, which is actually three different types, deoending on the size of the fields of the propety.) 


A value of 8 means that the property is a sequence of bytes, while a value of 16 means that the property is a sequence of 
words. T he difference between these two lies in the fact that the sequence of words will be byte swapped while the sequence 
of bytes will not be when read by a machine of the opposite byte order of the machine that originally wrote the property. For 
more information on how properties are formatted and stored, consult the Xlib manual. 


After the size of the fields has been specified, it is necessary to specify the type of each fidd (is it an integer, a string, an atom, 
or what?) T hisis done using one format character per field. If there are more fields in the property than format characters 
supplied, the last character will be reoeated as many times as necessary for the extra fields. The format characters and their 
meaning are as follows: 








a The field holds an atom number. A fidd of this type should be 
of size 32. 

b The field is a Boolean. A 0 means false while anything dse 
means true 

c The field is an unsigned number, a cardinal. 

i The field is a signed integer. 

m The field is a set of bit flags, 1 meaning on. 

s This fidd and the next ones— until either a0 or the end of the 


property— represent a sequence of bytes. T his format character 
is only usable with a field size of 8 and is most often used to 
represent a string. 

x The field is a hex number (like c but displayed in hex— most 
useful for displaying window ias and the like). 


An example format iS 32ica, which isthe format for a property of three fidds of 32 bits each— the first holding a signed 
integer, the second an unsigned integer, and the third an atom. 


The format of a dformat, unlike that of a format, is not so rigid. T he only limitations on a format is that one may not start 
with a letter or adash. T hisis so that it can be distinguished from a property name or an argument. A dformat isa text string 
containing special characters instructing that various fields be printed at various points in a manner similar to the formatting 
string used by printf. For example the dformat is ( $0, $1 \)\n would render the pornT 3, -4, which has a format of 32ii as 
is (3, -4 )\n. 


Any character other than a$, ?, \, ora( in adformat prints as itsef. To print out a¢, 2, \, or (, precedeit with a\. For 
example, to print out a$, use \$. Several special backslash sequences are provided as shortcuts. \n will cause a newline to be 
displayed, while \t will cause a tab to be displayed. \o, where o isan octal numbe,, will display character number o. 





A $ followed by anumber n causes field number n to be displayed. The format of the displayed field depends on the 
formatting character used to describe it in the corresponding format. In other words, if a cardinal is described by c, it will 
print in decimal, while if itis described by an x, it is displayed in hex. 
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If the field isnot present in the property (this is possible with some properties), <field not available> is displayed instead. 
$n+ will display field number n, then acomma, then fidd number n+1, then another comma, then ... until the last field 
defined. If fieldn is not defined, nothing is displayed. T his is useful for a property that isa list of values. 


A 7 isused to start aconditional expression, akind of if-then statement. 2exp (text ) will display text if and only if exp 
evaluates to non-zero. Thisis useful for two things. First, it allows fidds to be displayed if and only if a flag is set. And 
second, it allows a value such as a state number to be displayed as aname rather than as just a number. T he syntax of exp is as 
follows: 
exp ::= term | term=exp | !exp 
term ::= nn j $n j mn 





The: operator is a logical not, changing 0 to 1 and any non-zero value to @. = is an equality operator. N ote that internally, all 
expressions are evaluated as 32-bit numbers, so -1 isnot equal to 65535. = returns 1 if the two values are equal and a if not. n 
represents the constant valuen while sn represents the value of fied number n. mn is1 if flag number n in the first fidd 
having format character m in the corresponding format is 1; 0 otherwise. 


Examples: ?m3(count: $3\n) displaysfield 3 with alabe of count if and only if flag number 3 (count starts at 0!) ison. 
2$2=0 (Tru) ?!$2=0(False) displays the inverted value of fidd 2 asa Boolean. 


In order to display a property, xprop needs both a format and adformat. Before xprop uses its default values of a format of 32x 
and a dformat of " = { $0+ }\n", it searches several placesin an attempt to find more specific formats. First, a search ismade 
using the name of the property. If this fails, a search is made using the type of the property. T his allows type strine to be 
defined with one set of formats while allowing property ww_name, which is of type strine to be defined with a different 
format. In this way, the display formats for a given type can be overridden for specific propetties. 


The locations searched are in order: the format, if any, specified with the property name (asin 8x ww_Name), the formats 
defined by -¢ options in last to first order, the contents of the file specified by the -fs option if any, the contents of the file 
specified by the environmental variable xproprormats if any, and finally xprop’s built-in file of formats. 

The format of the files referred to by the -fs argument and the xproPrormaTs variable is one or more lines of the following 
form: 


name format [dformat ] 


W here name is either the name of a property or the nameof atype format isthe format to be used with name, and df or mat is 
the dformat to be used with name. If dformat isnot present, "=$0+\n" is assumed. 


EXAMPLES 


To display the name of the root window: xprop -root WM_NAME 

To display the window manage hints for the clock: xprop -name xclock WM_HINTS 
To display the start of the cut buffer: xprop -root -len 100 CUT_BUFFERO 

To display the point size of the fixed font: xprop -font fixed POINT_SIZE 

To display all the properties of window #0x200007: xprop -id 0x200007 


ENVIRONMENT 
DISPLAY To get default display. 
XPROPFORMATS Specifies the name of a file from which additional formats are 
to be obtained. 
SEE ALSO 


X(1), xwininfo(1) 
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AUTHOR 
Mark Lillibridge (MIT Project Athena) 


xrdb 


xrdb— X server resource database utility 


SYNOPSIS 


xrdb [-option ...] [filename] 


DESCRIPTION 


xrdb iS used to get or set the contents of the RESoURCE_MANAGER property on the root window of scree 0, or the 
SCREEN_RESOURCES property on the root window of any or all screens, or everything combined. You would normally run this 
program from your X startup file 


M ost X clients use the RESOURCE_MANAGER and SCREEN_RESOURCES properties to get user preferences about color, fonts, and so on 
for applications. H aving this information in the server (where it is available to all clients) instead of on disk solves the 
problem in previous versions of X that required you to maintain defaults files on every machine that you might use. It also 
allows for dynamic changing of defaults without editing files. 


T he RESOURCE_MANAGER property is used for resources that apply to all screens of the display. T he scREEN_RESOURCES property 
on each screen specifies additional (or overriding) resources to be used for that screen. (When thee is only one screen, 
SCREEN_RESOURCES iS normally not used; all resources are just placed in the RESOURCE_MANAGER propetty.) 


The file specified by filaaame (or the contents from standard input if - or no filenameis given) is optionally passed through 
theC preprocessor with the following symbols defined, based on the capabilities of the server being used: 


SERVERHOST=host name Thehostname portion of the display to which you are 
connected. 

SRVR_name T he SERVERHOSThostnamestring turned into a legal identifier. 
For example, my-dpy.1cs.mit.edu becomes sAvR my dpy lcs 
mit edu. 

HOST=host name The same as SERVERHOST. 

DISPLAY_NUM=num Thenumber of the display on the server host. 

CLIENTHOST=host name The name of the host on which xrab is running. 

CLNT_name The ctrentHost hostname string turned into a legal identifier. 
For example, “expo.1cs.mit.edu” DECOMESCLNT expo Ics mit 
edu. 

RELEASE=num The vendor release number for the server. The interpretation 
of this number will vary depending on venpor. 

REVISION=num Thex protocol minor version supported by this server 
(currently @). 

VERSION=num Thex protocol major version supported by this server (should 
always be 11). 

VENDOR="vendor” A string literal specifying the vendor of the server. 

VNDR_name The vendor name string turned into a legal identifier. For 
example, "MIT X Consortium" becomes vnoR_mIT_x Consortium. 

EXT_name A symbol is defined for each protocol extension supported by 


the server. Each extension string name is turned into a legal 
identifier. For example, "x3p-PEX" becomes EXT_X3D_PEX. 
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NUM_SCREENS=num 
SCREEN_NUM=num 
BITS PER_RGB=num 


CLASS=vi sual class 


CLASS_visualclass=visualid 
COLOR 


CLASS _visualclass_depth=num 


HEIGHT=num 
WIDTH=num 
PLANES=num 
X_RESOLUTION=num 
Y_RESOLUTION=num 


The total number of screens. 

Thenumber of the current screen (from zero). 

The number of significant bitsin an RGB color specification. 

This is the log base 2 of the number of distinct shades of each 

primary that thehardware can generate. N ote that it usually is 
not rdated to PLANES. 


One of staticGray, GrayScale, StaticColor, PseudoColor, 
TrueColor, DirectColor. T his is the visual class of the root 
window. 


The visual class of the root window in a form you can #ifdef 
on. The value is the numeric ia of the visual. 


Defined only if cLass is one of staticColor, PseudoColor, 
TrueColor, Of DirectColor 


A symbol is defined for each visual supported for the screen. 
The symbol includes the class of the visual and its depth; the 
value is the numeric ia of the visual. (If more than one visual 
has the same class and depth, the numeric id of the first one 
reported by the server is used.) 


Theheight of the root window in pixds. 

The width of the root window in pixels. 

The number of bit planes (the depth) of the root window. 
The x resolution of the screen in pixels per meter. 

They resolution of the screen in pixels per meter. 


SRVR_name, CLNT_name, VNDR_name, and EXT_name identifiers are formed by changing all characters other than letters and digits 


into underscores. 


Lines that begin with an exclamation mark (!) are ignored and may be used as comments. 


N ote that since xrdb can read from standard input, it can be used to change the contents of properties directly from a 


terminal or from a shdll script. 


OPTIONS 


xrdb program accepts the following options: 


-help 


-display display 


-all 


This option (or any unsupported option) will cause a brief 
description of the allowable options and parameters to be 
printed. 


This option specifies the X server to be used; see x(1). It also 
specifies the screen to use for the -screen option, and it 
specifies the screen from which preprocessor symbols are 
derived for the -globai option. 


This option indicates that operation should be peformed on 
the screen-independent resource property (RESOURCE_MANAGER), 
as well as the screen-specific property (SCREEN_RESOURCES) on 
every screen of the display. For example when used in 
conjunction with -query, the contents of all properties are 
output. For -load, -override, and -merge, the input file is 
processed once for each screen. T he resources that occur in 
common in the output for every screen are collected, and these 
are applied as the screen-independent resources. The 
remaining resources are applied for each individual per-screen 
property. This the default mode of operation. 
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-global This option indicates that the operation should only be 
performed on the screen-independent RESOURCE_MANAGER 
property. 

-screen This option indicates that the operation should only be 


performed on the screen_REsourceEs property of the default 
screen of the display. 

-screens This option indicates that the operation should be performed 
on the scREEN_RESOURCES property of each screen of the display. 
For -load, -override, and -merge, the input file is processed for 
each screen. 

-n This option indicates that changes to the specified properties 
(when used with -1oad, -override, OF -merge) or to the resource 
file (when used with -edit) should be shown on the standard 
output, but should not be performed. 





-quiet This option indicates that warning about duplicate entries 
should not be displayed. 
-cpp filename This option specifies the pathname of the C preprocessor 


program to be used. Although xrdb was designed to use C PP, 
any program that acts as a filter and accepts the -p, -1, and -u 
options may be used. 


-nocpp This option indicates that xrab should not run the input file 
through a preprocessor before loading it into propetties. 

-symbols This option indicates that the symbols that are defined for the 
preprocessor should be printed onto the standard output. 

-query This option indicates that the current contents of the specified 


properties should be printed onto the standard output. N ote 
that since preprocessor commandsin the input resource file are 
part of the input file not part of the property, they won’t 
appear in the output from this option. The -edit option can 
be used to merge the contents of properties back into the input 
resource file without damaging preprocessor commands. 

-load This option indicates that the input should be loaded asthe 
new value of the specified properties, replacing whatever was 
there; that is, the old contents are renoved. Thisis the default 
action. 

-override This option indicates that the input should be added to, 
instead of replacing, the current contents of the specified 
properties. N ew entries override previous entries. 

-merge This option indicates that the input should be merged and 
lexicographically sorted with, instead of replacing, the current 
contents of the specified propetties. 














-remove This option indicates that the specified properties should be 
removed from the server. 
-retain This option indicates that the server should be instructed not 


to reset if xrdb isthe first client. T his should never be necessary 
under normal conditions, since xdm and xinit always act as the 
first client. 

-edit filename This option indicates that the contents of the specified 
properties should be edited into the given file, replacing any 
values already listed there. This allows you to put changes that 
you have made to your defaults back into your resource file, 
preserving any comments or preprocessor lines. 
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-backup string This option specifies a suffix to be appended to the filarame 
used with -edit to generate a backup file 
-Dname [=val ue ] This option is passed through to the preprocessor and is used 
to define symbols for use with conditionals such as #ifdef. 
Una me This option is passed through to the preprocessor and is used 
to remove any definitions of this symbol. 
-Idirectory This option is passed through to the preprocessor and is used 
to specify a directory to search for files that are referenced with 
#include. 
FILES 
Generalizes ~/.xdefaults files 
SEE ALSO 
x(1), Xlib Resource M anager documentation, xt resource documentation 
ENVIRONMENT 
DISPLAY To figure out which display to use 
BUGS 
The default for no arguments should be to query, not to overwrite, so that it is consistent with other programs. 
AUTHORS 


Bob Schafler and Phil Karlton, rewritten from the original by Jim Gettys 
X Verson 11 Release 6 
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xrefresh— Refresh all or part of an X screen 


SYNOPSIS 


xrefresh [-option ...] 


DESCRIPTION 


xrefresh isasimple X program that causes all or part of your screen to be repainted. This is useful when system messages 
have messed up your screen. xrefresh maps a window on top of the desired area of the screen and then immediately unmaps 
it, causing refresh events to be sent to all applications. By default, a window with no background is used, causing all 
applications to repaint smoothly. H owever, the various options can be used to indicate that a solid background (of any color) 
or the root window background should be used instead. 


ARGUMENTS 
-white Use awhite background. T hescrem just appears to flash 
quickly, and then repaint. 
-black Use a black background (in effect, turning off all of the 


electron guns to thetube). T his can be somewhat disorienting 
as everything goes black for amoment. 


-solid color Use asolid background of the specified color. T ry green. 
-root Use the root window background. 


-none This is the default. All of the windows simply repaint. 
-geometry WxH+X+Y Specifies the portion of the screen to be repainted; see x(1). 
-display display This argument allows you to specify the server and screm to 
refresh; see x(1). 
X DEFAULTS 
The xrefresh program uses the routine xGetDefault (3x) to read defaults, so its resourcenames are all capitalized. 
Black, White, Solid, None, Root D etermines what sort of window background to use 
Geometry D etermines the area to refresh. N ot very useful. 
ENVIRONMENT 
DISPLAY To get default host and display number. 
SEE ALSO 
x(1) 
BUGS 
It should have just one default type for the background. 
AUTHORS 


Jim Gettys (Digital Equipment Corporation, MIT Project Athena) 
X Verson 11 Release 6 
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Xserver— X Window System display server 


SYNOPSIS 


X [option ...] 


DESCRIPTION 


x isthe generic name for the X Window System display server. It is frequently a link or a copy of the appropriate server 
binary for driving the most frequently used server on agiven machine. 


STARTING THE SERVER 


Thex server is usually started from the X Display M anager program xdm(1). This utility isrun from the system boot files and 
takes care of keeping the server running, prompting for usernames and passwords, and starting up the user sessions. 


Installations that run more than one window system may need to use the xinit(1) utility instead of xam. H oweve’, xinit isto 
be considered a tool for building startup scripts and is not intended for use by end users. Site administrators are strongly 
urged to use xdm, or build other interfaces for novice users. 


The x server may also be started directly by the user, though this method is usually reserved for testing and is not recom- 
mended for normal operation. On some platforms, the user must have special permission to start the x server, often because 
access to certain devices. (For example, /dev/mouse is restricted.) 


W hen the x server starts up, it typically takes over the display. If you are running on a workstation whose console is the 
display, you may not be able to log into the console while the server is running. 
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OPTIONS 


All of thex servers accept the following command-line options: 


:displaynumber 


-a number 


-ac 


-audit | evel 


-auth authorization-file 


be 


-bs 
-c 
c volume 


-cc class 


-co filename 


-config filename 


-core 


-dpi resolution 


-deferglyphs whi chfonts 


-f volume 
-fce cursorFont 
-fn font 


Thex server runs as the given disp! aynumber , which by default 
isa. If multiple x servers are to run Smultaneously on a host, 
each must have a unique display number’. See the “D isplay 

N ames” subsection of thex(1) manual page to learn how to 
specify which display number clients should try to use 

Sets pointer acceleration (that is, the ratio of how much is 
reported to how much the user actually moved the pointer). 
Disables host-based access control mechanisms. Enables access 
by any host, and permits any host to modify the access control 
list. Use with extreme caution. T his option exists primarily for 
running test suites remotd y. 

Sets the audit trail level. The default level is 1, meaning only 
connection rejections are reported. Leva 2 additionally reports 
all successful connections and disconnects. Level 0 turns off 
the audit trail. Audit lines are sent as standard error output. 
Specifies a file which contains a collection of authorization 
records used to authenticate access. See also the xam and 
Xsecurity Manual pages. 

Disables certain kinds of error checking, for bug compatibility 
with previous releases (for example, to work around bugs in 
R2 and R3 xterms and toolkits). D eorecated. 

Disables backing store support on all screens. 

Turns off key-click. 

Sets key-click volume (allowable range 0-100). 

Sets the visual class for the root window of color screens. The 
class numbers are as specified in the x protocol. N ot obeyed by 
all servers. 

Ses name of RGB color database T he default is <xRoot>/1ib/ 
X11/rgb, where <xroot> refers to the root of the X11 install 
tree 

Reads more options from the given file. O ptions in the file 
may be separated by newlines if desired. If a # character 
appears on aline, all characters between it and the next 
newline are ignored, providing a simple commenting facility. 
The -config option itself may appear in the file. 

Causes the server to generate a core dump on fatal errors. 

Sets the resolution of the screen, in dots per inch. To be used 
when theserver cannot determine the screen size from the 
hardware. 

Specifies the types of fonts for which the server should attempt 
to use deferred glyph loading. whichfonts can bea11 (all fonts), 
none (no fonts), or 16 (16-bit fonts only). 

Sets feep (bell) volume (allowable range: 0-100). 

Sets default cursor font. 

Sets the default font. 


-fp fontPath 


-I 
-kb 
-p minutes 


-pn 


-r 
r 

-s minutes 
-su 


-t number 


erminate 


oO seconds 


-tst 





ttyxx 


-x extension 


SERVER DEPENDENT OPTIONS 


Some x servers accept the following options: 
-ld kilobytes 


-lf files 


-Is kilobytes 
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Sets the search path for fonts. This path isa comma-separated 
list of directories that the X server searches for font databases. 
-help prints a usage message. 

Causes all remaining command-line arguments to be ignored. 
Disables the xkeyBoarb extension if present. 

Sets screen saver pattern cycle time in minutes. 

Permits the server to continue running if it fails to establish all 
of its well-known sockets (connection points for clients), but 
establishes at least one 

Turns off auto-repeat. 

Turns on auto-repeat. 

Sets screen saver time-out time in minutes. 

Disables save under support on all scres. 

Sets pointer accderation threshold in pixes (that is, sets after 
how many pixds pointer acceleration should take effect). 
Causes the server to terminate at server reset, instead of 
continuing to run. 

Sets default connection timeout in seconds. 

Disables all testing extensions (for example, xTEST, XTrap, 
XTestExtension1), 

Ignored, for servers started the ancient way (from init). 

Sets video-off screen saver preference. 

Sets video-on screen saver preference 

Forces the default backing-store of all windows to bewhen- 
Mapped. T hisis a backdoor way of getting backing-store to 
apply to all windows. Although all mapped windows will have 
backing-store, the backing-store attribute value reported by the 
server for a window will be the last value established by a 
client. If it has never been set by aclient, the server will report 
the default value NotUseful. This behavior is required by the 
X protocol, which allows the server to exceed the client’s 
backing-store expectations but does not provide a way to tell 
the client that it is doing so. 

Loads the specified extension at init. This is ano-op for most 
implementations. 


Sets the data space limit of the server to the specified number 
of kilobytes. A value of zero makes the data size as large as 
possible. T he default value of -1 leaves the data space limit 
unchanged. 

Sets the number- of-open-files limit of the server to the 
specified number. A value of zero makes the limit as large as 
possible. T he default value of -1 leaves the limit unchanged. 
Sets the stack space limit of the serve to the specified number 
of kilobytes. A value of zero makes the stack size as large as 
possible. T he default value of -1 leaves the stack space limit 
unchanged. 
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-logo 


nologo 


XDMCP OPTIONS 


Turns on the X Window System logo display in the screen 
saver. There is currently no way to change this from a client. 
Turns off the X Window System logo display in the screen 
saver. There is currently no way to change this from a client. 


x servers that support XD MCP have the following options. (See the X Display M anager Control Protocol specification for 


more information.) 


-query host-name 


-broadcast 


-indirect host-name 
-port port-num 


-class display-class 


-cookie xdm-auth-bits 


-displayID display-id 


XKEYBOARD OPTIONS 


Enable XD M CP and send query packets to the specified host. 
Enable XD M CP and broadcast Broadcastauery packets to the 
network. The first responding display manager will be chosen 
for the session. 

Enable XD M CP and send Indirectauery packets to the 
specified host. 

Use an alternate port number for XD M CP packets. M ust be 
specified before any -query, -broadcast, OF -indirect options. 
XDMCP hasan additional display qualifier used in resource 
lookup for display-specific options. T his option sets that value 
by default it is mIT-Unspecified (not a very useful value). 

W hen testing XpM-AUTHENTICATION-1, a private key is shared 
between the server and the manager. T his option sets the value 
of that private data (not that it is very private, being on the 
command line’). 

Ye another XD M CP-specific value, this one allows the display 
manager to identify each display so that it can locate the 
shared key. 


x servers that support the xkeyBoarp extension accept the following options: 


-xkbdir directory 
-xkbmap filename 
[+-]accessx 


-ar1 milliseconds 


-ar2 milliseconds 


Base directory for keyboard layout files 

Keyboard description to load on startup 

Enable(+) or disable(-) AccessX key sequences 
Sets the length of timein milliseconds that a key must be 
depressed before auto-repeat starts 

Sets the length of timein milliseconds that should dapse 
between auto-repeat- generated keystrokes 


M any servers also have device specific command-line options. See the manual pages for the individual servers for more 


details. 
NETWORK CONNECTIONS 


The x server supports client connections via a platform-dependent subset of the following transport types: TCPIP, UNIX 
Domain sockets, D ECnet, and several varieties of SVR 4 local connections. See the “Display N ames” subsection of the x(1) 
manual page to learn how to specify which transport type clients should try to use 


SECURITY 


Thex server implenents a platform-dependent subset of the following authorization protocols: -m1T-MAGICCOOKIE-1, XDM- 
AUTHORIZATION-1, SUN-DES-1, ANd MIT-KERBEROS -5. See the xsecurity(1) manual page for information on the operation of these 


protocols. 
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Authorization data required by the preceding protocols is passed to the server in a private file named with the-auth 
command-line option. Each time the server is about to accept the first connection after a reset (or when the server is 
starting), it reads this file. If this file contains any authorization records, the local host isnot automatically allowed access to 
the server, and only clients that send one of the authorization records contained in the file in the connection setup informa 
tion will be allowed access. See the xau manual page for a description of the binary format of this file See xauth(1) for 
maintenance of thisfile and distribution of its contents to remote hosts. 


The x server also uses a host-based access control list for deciding whether or not to accept connections from clients on a 
particular machine If no other authorization mechanism is being used, this list initially consists of the host on which the 
server is running as well as any machines listed in the file /etc/xn .nosts, where n isthe display number of the server. Each 
lineof the file should contain athe an Internet hostname (for example expo.1cs.mit.edu) or aD ECné hostname in double 
colon format (for example, hydra: :). T here should be no leading or trailing spaces on any lines. For example, 
joesworkstation 

corporate.company.com 

star:: 

bigcpu:: 


Users can add or remove hostsfrom this list and enable or disable access control using the xnost command from the same 
machine as the server. 


Thex protocol intrinsically does not have any notion of window operation permissions or place any restrictions on what a 
client can do; if a program can connect to a display, it has full run of the screen. Sites that have better authentication and 
authorization systens might wish to make use of the hooks in the libraries and the server to provide additional security 
modds. 


SIGNALS 
The x server attaches special meaning to the following signals: 


SIGHUP This signal causes the server to closeall existing connections, 
free all resources, and restore all defaults. It issent by the 
display manager whenever the main user’s main application 
(usually an xterm or window manage’) exits to force the server 
to clean up and prepare for the next user. 

SIGTERM This signal causes the server to exit cleanly. 


SIGUSR1 This signal is used quite differently from either of the above. 
When the server starts, it checks to see if it has inherited 
SIGUSR1 aS SIG_IGN instead of the usual stc_DFL. In this case, 
the server sends a sicusri to its parent process after it has set 
up the various connection schemes. xam uses this feature to 
recognize when connecting to the server is possible 


FONTS 


Thex server can obtain fonts from directories or from font servers. The list of directories and font servers the x server uses 
whe trying to open a font is controlled by the font path. 


The default font path is 


<XRoot>/1lib/X11/fonts/misc/, 
<XRoot>/1lib/X11/fonts/Speedo/, 
<XRoot>/1lib/X11/fonts/Type1/, 
<XRoot>/1lib/X11/fonts/75dpi/ 
<XRoot>/1lib/X11/fonts/100dpi/ 


where <xRoot> refers to the root of the X11 install tree. 
The font path can be set with the -fp option or by xset(1) after the server has started. 
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FILES 
/etc/Xn .hosts Initial access control list for display number n 
<XRoot>/1lib/X11/fonts/misc 
<XRoot>/1lib/X11/fonts/75dpi 


<xRoot>/1ib/X11/fonts/100dpi Bitmap font directories 
<XRoot>/1lib/X11/fonts/Speedo 

<XRoot>/1ib/X11/fonts/Type1 Outline font directories 

<XRoot>/1ib/X11/fonts/PEX PEX font directories 

<XRoot>/1ib/X11/rgb.txt Color database 

/tmp/.X11-unix/Xn UNIX domain socket for display number n 

/tmp/reXn Kerberos 5 replay cachefor display number n 
/usr/adm/Xnmsgs Error log file for display number n if run from init(8) 
<XRoot>/1ib/X11/xdm/xdm-errors D efault error log file if the server is run from xdm(1) 


N ote: <xRoot> refers to the root of the X11 install tree. 


SEE ALSO 
General information: x(1) 
Protocols: X Window System Protocol, The X Font Service Protocol, X Display M anager C ontrol Protocol 
Fonts: bdftopcf(1), mkfontdir(1), xfs(1), xisfonts(1), xfontse1(1), xfd(1), X Logical Font D escription Conventions 
Security: xsecurity(1), xauth(1), xau(1), xdm(1), xhost(1) 
Starting the server: xdm(1), xinit(1) 
Controlling the server once started: xset(1), xsetroot(1), xhost(1) 


Server-specific man pages: xdec(1), xmact1(1), xsun(1), xnest(1), xvfb(1), xF86 Acce1(1), XF86 Mono(1), xF86 SvGA(1), xF86 
vGA16(1), xFree86(1) 


Server internal documentation: “D einition of the Porting Layer for the X v11 Sample Server,” “Strategies for Porting the X 
v11 Sample Server,” “Godzilla’s Guide to Porting the X v11 Sample Sever” 


AUTHORS 


The sample server was originally written by Susan Angebranndt, Raymond D rewry, Philip Karlton, and Todd N ewman, 
from Digital Equipment C orporation, with support from a large cast. It has since been extensively rewritten by Keith 
Packard and Bob Schefler, from MIT. 
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xset 


xset— User preference utility for X 


SYNOPSIS 
xset [-display display] [-b] [b on/off] [b [volume [pitch [duration]]] [[-]bc] 
[-c] [c on/off] [c [volume]] [[-+]fp[-+=] path[,path[,...]]] [fp default] 


[fp rehash] [[-]led [integer]] [led on/off] [m[ouse] [accel _mult[/accel div] 
[threshold]]] [m[ouse] default] [p pixel color] [[-]r [keycode]] [r on/off] 
[s [length [period]]] [s blank/noblank] [s expose/noexpose] [s on/off] 

[s default] [s activate] [s reset] [q] 


acl 


DESCRIPTION 
This program is used to set various user preference options of the display. 
OPTIONS 
-display display This option specifies the server to use; see x(1). 
b Theb option controls bell volume, pitch, and duration. This 


option accepts up to three numerical parameters, a preceding 
dash (-), or an on/off flag. If no parameters are given, or the on 
flag is used, the system defaults will be used. If the dash or off 
is given, the bd will be turned off. If only onenumarical 
parameter is given, the bell volume will be set to that value, as 
a percentage of its maximum. Likewise, the second numerical 
parameter specifies the bal pitch, in hertz, and the third 
numerical parameter specifies the duration in milliseconds. 

N ote that not all hardware can vary the bal characteristics. 
Thex server will set the characteristics of the bal as closely as 
it can to the user’s specifications. 


be The be option controls bug compatibility mode in the server, 
if possible; a preceding dash (-) disables the mode otherwise, 
the mode is enabled. Various pre-R 4 clients pass illegal values 
in some protocol requests, and pre R4 servers did not correctly 
generate errors in these cases. Such clients, when run against 
an R4 serve, will terminate abnormally or otherwise fail to 
operate correctly. Bug compatibility mode explicitly rantro- 
duces certain bugs into the x server, so that many such clients 
can still be run. This mode should be used with care new 
application development should be done with this mode 
disabled. The server must support the m1T - SUNDRY -NONSTANDARD 
protocol extension in order for this option to work. 

c Thec option controls key click. This option can take an 
optional value, a preceding dash (-), or an on/off flag. If no 
parameter or the on flag is given, the system defaults will be 
used. If the dash or off flag is used, key click will be disabled. 
If avalue from 0 to 100 is given, it is used to indicate volume 
as a percentage of the maximum. T hex server will set the 
volume to the nearest value that the hardware can support. 

fp= path,... The fp= sets the font path to the entries given in the path 
argument. T he entries are interpreted by the server, not by the 
client. T ypically, they are directory names or font server 
names, but the interpretation is server-dependent. 


fp default The default argument causes the font path to be reset to the 
server's default. 
fp rehash The rehash argument resets the font path to its current value, 


causing the server to reread the font databases in the current 
font path. This is generally only used when adding new fonts 
to afont directory (after running mkfontdir to recreatethe 
font database). 

-fp Or fp- The -fp and fp- options renove elements from the current 
font path. They must be followed by a comma-separated list of 
entries. 
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fp OF fp 


led 


This fp and fp options prepend and append denents to the 
current font path, respectively. They must be followed by a 
comma-separated list of entries. 


The 1ed option controls the keyboard Leps. T his controls the 
turning on or off of oneor all of the eps. It accepts an 
optional integer, a preceding dash (-) or an on/off flag. If no 
parameter or the on flag is given, all Leos are turned on. If a 
preceding dash or the flag off is given, all Leps are turned off. 
If a value between 1 and 32 is given, that Lep will be turned 
on or off depending on the existence of a preceding dash. A 
common cep that can be controlled is the caps Lock LED. xset 
led 3 would turn led #3 on. xset -1ed 3 would turn it off. 
The particular Leo values may refer to different Lens on 
different hardware 


Them option controls the mouse parameters. T he parameters 
for the mouse are acceleration and threshold. T he accelera- 
tion can be specified as an integer, or asasimple fraction. The 
mouse, or whatever pointer the machine is connected to, will 
gO acceleration times as fast when it travas more than 
threshold pixelsin ashort time This way, the mouse can be 
used for precise alignment when it is moved slowly, yet it can 
be set to travel across the screen in a flick of the wrist when 
desired. Oneor both parameters for them option can be 
omitted, but if only oneis given, it will be interpreted as the 
accderation. lf no parameters or the flag default is used, the 
system defaults will be set. 


The p option controls pixel color values. The parameters are 
the color map entry number in decimal, and a color specifica- 
tion. The root background colors may be changed on some 
servers by altering the entries for BlackPixel and WhitePixel. 
Although these are often @ and 1, they need not be Also, a 
server may choose to allocate those colors privatdy, in which 
case an error will be generated. The map entry must not bea 
read-only color, or an error will result. 


Ther option controls the auto-repeat. If a preceding dash 
or the off flag is used, auto-repeat will be disabled. If no 
parameters or the on flag is used, auto-repeat will be enabled. 
If a specific keycode is specified as a parameter, auto-repeat 
for that keycode is enabled or disabled. 


Thes option lets you set the screen saver parameters. This 
option accepts up to two numevical parameters, a blank/ 
noblank flag, an expose/noexpose flag, an on/off flag, an 
activate/reset flag, or the default flag. If no parameters or 
the default flag is used, the system will be set to its default 
screen saver characteristics. T he on/off flags simply turn the 
screen saver functions on or off. The activate flag forces 
activation of screen saver even if the screen saver had been 
turned off. The reset flag forces deactivation of screen saver 
if it is active. T he blank flag sets the preference to blank the 
video (if the hardware can do so) rather than display a 
background pattern, while noblank sets the preference to 
display a pattern rather than blank the video. T he expose flag 
sets the preference to allow window exposures (the server can 
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freely discard window contents), while noexpose sets the 
preference to disable screen saver unless the server can 
regenerate the screens without causing exposure events. The 
length and period parameters for the screen saver function 
determines how long the server must be inactive for screen 
saving to activate and the period to change the background 
pattern to avoid burn in. The arguments are specified in 
seconds. If only onenumerical parameter is given, it will be 
used for the length. 


q Theq option gives you information on the current settings. 
T hese settings will be reset to default values when you log out. 
N ote that not all x implementations are guaranteed to honor all of these options. 


SEE ALSO 


X(1), Xserver(1), xmodmap(1), xrdb(1), xsetroot(1) 


AUTHOR 
Bob Schafler (MIT Laboratory for Computer Science), D avid Krikorian (MIT Project Athena; X11 version) 
X Verson 11 Reease 6 
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xsetroot— Root window parameter setting utility for x 


SYNOPSIS 
xsetroot [-help] [-def] [-display display] [-cursor cursorfile maskfile] 
[-cursor_name cursorname] [-bitmap filename] [-mod x y] [-gray] [-grey] 
[-fg color] [-bg color] [-rv] [-solid color] [-name string] 
DESCRIPTION 


The setroot program allows you to tailor the appearance of the background (root) window on a workstation display running 
x. Normally, you experiment with xsetroot until you find a personalized look that you like, then put the xsetroot command 
that produces it into your x startup file If no options are specified, or if -def is specified, the window is reset to its default 
state. The -def option can be specified along with other options and only the nonspecified characteristics will be reset to the 
default state. 


Only one of the background color/tiling changing options (-solid, -gray, -grey, -bitmap, and -mod) may be specified at a 
time. 


OPTIONS 


The various options are as follows: 


-help Print a usage message and exit. 

-def Reset unspecified attributes to the default values. (Restores the 
background to the familiar gray mesh and the cursor to the 
hollow x shape) 

-cursor cursorfile maskfile This lets you change the pointer cursor to whatever you want 
when the pointer cursor is outside of any window. Cursor and 
mask files are bitmaps (little pictures), and can be made with 
the bitmap(1) program. You probably want the mask file to be 
all black until you get used to the way masks work. 
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-cursor_name cursorname This lets you change the pointer cursor to one of thestandard 
cursors from the cursor font. Refer to Appendix B of thex 
protocol for the names (except that the xc prefix is dided for 
this option). 

-bitmap filename Use the bitmap specified in the file to set the window pattern. 
You can make your own bitmap files (little pictures) using the 
bitmap(1) program. The entire background will be made up of 
repeated “tiles” of the bitmap. 

-mod x y This is used if you want a plaid-like grid pattern on your 
screen. x and y areintegers ranging from 1 to 16. Try the 
different combinations. Zero and negative numbers are taken 


as 1. 
-gray M ake the entire background gray. (Easier on the eyes.) 
-grey M ake the entire background grey. 
-fg color Usecolor asthe foreground color. Foreground and back- 


ground colors are meaningful only in combination with 
-cursor, -bitmap, OF -mod. 


-bg color Usecolor asthe background color. 

“PV This exchanges the foreground and background colors. 
Normally the foreground color is black and the background 
color is white 

-solid color This sets the background of the root window to the specified 
color. This option is only useful on color servers. 

-name string Set the name of the root window to string. There isno default 


value. U sually anameis assigned to a window so that the 
window manager can use a text representation when the 
window isiconified. T his option is unused because you can’t 
iconify the background. 


-display display Specifies the server to connect to; see x(1). 


SEE ALSO 
x(1), xset(1), xrdb(1) 


AUTHOR 
Mark Lillibridge (MIT Project Athena) 
X Verson 11 Release 6 
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xsm— X Session M anager 
SYNOPSIS 

xsm [-display display] [-session sessionName] [-verbose] 
DESCRIPTION 


xsm iS. a session manager. A session is a group of applications, each of which has a particular state. xsm allows you to create 
arbitrary sessions. For example, you might have a light session, adevelopment session, Or an xterminal session. Each session 
can have its own set of applications. Within a session, you can perform acheckpoint to save application state, or a shutdown 
to save state and exit the session. W hen you log back in to the system, you can load a specific session, and you can delete 
sessions you no longer want to keep. 


i 


Some session managers simply allow you to manually specify a list of applications to be started in a session. xsm is more 
powerful because it lets you run applications and have then automatically become part of the session. On asimple leva, xsm 
is useful because it gives you this ability to easily define which applications arein a session. T he true power of xsm, however, 
can be taken advantage of when more and more applications learn to save and restore thar state. 


OPTIONS 
-display display Causes xsm to connect to the specified X display. 
-session sessionName Causes xsm to load the specified session, bypassing the session 
menu. 
-verbose Turns on debugging information. 
SETUP 


.xsession FILE 


Using xsm requires a change to your .xsession file 


The last program executed by your .xsession file should be xsm. W ith this configuration, when the user chooses to shut 
down the session using xsm, thesession will truly be over. 


Because the goal of the session manager is to restart clients when logging into a session, your .xsession file, in general, should 
not directly start up applications. Rather, the applications should be started within a session. When xsm shuts down the 
session, xsm will Know to restart these applications. N ote however, that there are some types of applications that are not 
“session aware”. xsm enables you to manually add these applications to your session. (See the subsection titled “Client List.”) 


SM_SAVE_DIR ENVIRONMENT VARIABLE 


If the sm_save_prR environment variable is defined, xsm will save all configuration files in this directory. O therwise, they will 
be stored in the user's home directory. Session-aware applications are also encouraged to save their checkpoint files in the 
SM_SAVE_DIR directory, although the user should not depend on this convention. 


DEFAULT STARTUP APPLICATIONS 


The first time xsm is started, it will need to locate a list of applications to start up. For example, this list might includea 
window manager, a session management proxy, and an xterm. xsm will first look for the file .xsmstartup in the user’s home 
directory. If that file does not exist, it will look for the system. xsm file that was set up at installation time. N ote that xsm 
provides a failsafe option when the user chooses a session to start up. The failsafe option simply loads the default 
applications described above. 


Each line in the startup file should contain a command to start an application. A sample startup file might look this: 


<start of file> 
twm 

smproxy 

xterm 

<end of file> 


STARTING A SESSION 


W hen xsm starts up, it first checks to see if the user previously saved any sessions. If no saved sessions exist, xsm starts up a set 
of default applications (as described above in the subsection titled “D efault Startup Applications’). If at least one session 
exists, a Session menu is presented. The[-session sessionName] option forces the specified session to be loaded, bypassing 
the session menu. 


THE SESSION MENU 


The Session menu presents the user with a list of sessions to choose from. T he user can change the currently selected session 
with the mouse, or by using theup and down arrows on the keyboard. N ote that sessions that are locked (that is, running on 
a different display) cannot beloaded or deleted. 
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The following operations can be performed from the Session menu: 


Load Session Pressing this button will load the currently selected session. 
Alternatively, hitting the Return key will also load the 
currently sdlected session, or the user can double-click a session 
from the list. 

D elete Session This operation will delete the currently selected session, along 
with all of the application checkpoint files associated with the 
session. After pressing this button, the user will be asked to 
press the button a second timein order to confirm the 
operation. 

D efault/Fail Safe xsm will start up a set of default applications (as described 
earlier in the section titled “D efault Startup Applications”). 
This is useful when the user wants to start a fresh session, or if 
the session configuration files were corrupted and the user 
wants a failsafe session. 

Cancel Pressing this button will cause xsm to exit. It can also be used 
to cancel aD elete Session operation. 


CONTROLLING A SESSION 


After xsm determines which session to load, it brings up its main window, then starts up all applications that are part of the 
session. The title bar for the session manager's main window will contain the name of the session that was loaded. 


The following options ae available from xsm’s main window: 


Client List Pressing this button brings up a window containing alist of all 
clients that arein the current session. For each client, the host 
machine that the client is running on is presented. As clients 
are added and renoved from thesession, thislist is updated 
to reflect the changes. T he user is able to control how these 

clients are restarted. 

y pressing the View Propatties button, the user can view the 

session management properties associated with the currently 

selected client. 

By pressing the Clone button, the user can start a copy of the 

selected application. 

By pressing the Kill Client button, the user can removea client 

from the session. By selecting a restart hint from the Restart 

Hint menu, the user can control the restarting of aclient. The 

following hints are available: 

m TheRestart If Running hint indicates that the client 
should be restarted in the next session if it is connected to 
the session manager at the end of the current session. 

m TheRestart Anyway hint indicates that the client should 
be restarted in the next session even if it exits before the 
current session is terminated. 

m TheRestart |mmediately hint is similar to the Restart 
Anyway hint, but in addition, the client is meant to run 
continuously. If the client exits, the session manager will 
try to restart it in the current session. 

m TheRestart N ever hint indicates that the client should not 
be restarted in the next session. 


w 





Session Log... 


Checkpoint 
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N ote that all X applications may not be session aware. 
Applications that are not session aware are ones that do not 
support the X Session M anagement Protocol or they cannot 
be detected by the Session M anaganent Proxy. (See the 
subsection titled “The Proxy.”). xsm allows the user to 
manually add such applications to the session. T hebottom of 
the Client List window contains atext entry fidd into which 
application commands can be typed. Each command should 
go on its own line. This information will be saved with the 
session at checkpoint or shutdown time When the session is 
restarted, xsm will restart these applications in addition to the 
regular session aware applications. Pressing the D one button 
removes the Client List window. 

The Session Log window presents useful information about 
the session. For example, when a session is restarted, all of the 
restart commands will be displayed in the log window. 

By performing a checkpoint, all applications that are in the 
session are asked to save their state N ot every application will 
save its complete state, but at aminimum, the session manager 
is guaranteed that it will receive the command required to 
restart the application (along with all command-line options). 
A window manager participating in the session should 
guarantee that the applications will come back up with the 
same window configurations. 

If the session being checkpointed was never assigned a name, 
the user will be required to specify a session name O therwise, 
the user can perform the checkpoint using the current session 
name, or anew session name can be specified. If the session 
name specified already exists, the user will be given the 
opportunity to specify a different name or to overwrite the 
already existing session. N ote that a session that is locked can 
not be overwritten. 

When performing acheckpoint, the use’ must specify a save 
Type that informs the applications in the session how much 
state they should save. 

The Local type indicates that the application should save 
enough information to restore the state as seen by the user. It 
should not affect the state as seen by other users. For example 
an editor would create a temporary file containing the contents 
of its editing buffer, the location of the cursor, and so on. 
The Global type indicates that the application should commit 
all of its data to permanent, globally accessible storage. For 
example, the editor would simply save the edited file 

T he Both type indicates that the application should do both of 
these. For example, the editor would save the edited file then 
create a temporary file with information such as the location of 
the cursor, and so on. 

In addition to the save Type, the user must specify an Interact 
Style. 

The None type indicates that the application should not 
interact with the user while saving state. 
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Shutdown 


THE PROXY 


The Errors type indicates that the application may interact 
with the user only if an error condition arises. 

The Any type indicates that the application may interact with 
the user for any purpose N ote that xsm will only allow one 
application to interact with the user at a time. 

After the checkpoint is completed, xsm will, if necessary, 
display a window containing the list of applications that did 
not report a successful save of state. 

A shutdown provides all of the options found in a checkpoint, 
but, in addition, can cause the session to exit. N ote that if the 
interaction style is Errors or Any, the user may cancel the 
shutdown. The user may also cancel the shutdown if any of 
the applications report an unsuccessful save of state The user 
may choose to shut down the session with or without 
performing a checkpoint. 


Because not all applications have bem ported to support the X Session M anagement Protocol, a proxy service exists to enable 
“old” clients to work with the session manage. In order for the proxy to detect an application joining a session, one of the 


following must be true: 
m Theapplication maps a top- 


evel window containing the ww_cL1EnT_LEADER property. T his property provides a pointer to 


the client leader window that contains the wm_CLASS, WM_NAME, WM_COMMAND, and WM_CLIENT_MACHINE properties. 


or 





m = Theapplication maps a top- 


evel window that does not contain the ww_cLIENT_LEADER propetty. H oweve,, this top-level 


window contains the ww_CLASs, WM_NAME, WM_COMMAND, and WM_CLIENT_MACHINE properties. 


An application that supports the wm_save_yourseLF protocol will receive a ww_SAVE_YOURSELF Client message each time the 
session manager issues a checkpoint or shutdown. T his allows the application to save state. If an application does not support 
the wm_SAve_yoursELF protocol, then the proxy will provide enough information to the session manage to restart the 





application (using wm_commanp), but no state will be restored. 


REMOTE APPLICATIONS 


xsm requires a remote execution protocol in order to restart applications on remote machines. Currently, xsm supports the 
rstart protocol. !n order to restart an application on remote machine X, machineX must have rstart installed. In the 
future, additional renote execution protocols may be supported. 


SEE ALSO 


smproxy(1), rstart(1) 


AUTHORS 


Ralph M or (X Consortium), Jordan Brown (Quarterdeck 0 ffice Systems) 
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xsmclient— X session manager tester 


SYNOPSIS 


xsmclient [ TBD ] 
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xtdcmap 


DESCRIPTION 


The xsmclient program is used to test the session manager 


AUTHOR 
Ralph M or (X Consortium) 


X Verdon 11 Reease 6 
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xstdcmap— X standard colormap utility 


SYNOPSIS 


xstdcmap [-all] [-best] [-blue] [-default] [-delete map] [-display display] 
[-gray] [-green] [-help] [-red] [-verbose] 


DESCRIPTION 


The xstdemap utility can be used to selectively define standard colormap properties. It isintended to be run from a user's X 
startup script to create standard colormap definitionsin order to facilitate sharing of scarce colormap resources among 
clients. W here at all possible, colormaps are created with read-only allocations. 


OPTIONS 
The following options may be used with xstdcmap: 


-all This option indicates that all six standard colormap properties 
should be defined on each screen of the display. N ot all screens 
will support visuals under which all six standard colormap 
properties are meaningful. xst-dcmap will determine the best 
allocations and visuals for the colormap propetties of a screen. 
Any previously existing standard colormap propeties will be 


replaced. 
-best This option indicates that the raB_BesT_map should be defined. 
-blue This option indicates that the raB_BLUE_MaP should be defined. 
-default This option indicates that the raB_DEFAULT_mAP should be 
defined. 
-delete map This option specifies that a specific standard colormap 


propetty, or all such properties, should be removed. map may 
be one of: default, best, red, green, blue, gray, Of all. 





-display display This option specifies the host and display to use see x(1). 

-gray This option indicates that the raB_Gray_map should be defined. 

-green This option indicates that the raB_GREEN_wap should be 
defined. 

-help This option indicates that a brief description of the command- 


line arguments should be printed on the standard error. This 
will be done whenever an unhandled argument is given to 





xstdcemap. 
-red This option indicates that the raB_RED_mapP should be defined. 
-verbose This option indicates that xstdcmap should print logging 


information asit parses its input and defines the standard 
colormap properties. 
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ENVIRONMENT 
DISPLAY To get default host and display number 


SEE ALSO 
x(1) 
AUTHOR 


Donna Converse (MIT X Consortium) 
X Version 11 Release 6 
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xterm— T erminal emulator for X 
SYNOPSIS 

xterm [-toolkitoption ...] [-option ...] 
DESCRIPTION 


The xterm program is ateaminal emulator for the X Window System. It provides DEC VT 102- and Tektronix 4014- 
compatible terminals for programs that can’t use the window system directly. If the underlying operating system supports 
terminal resizing capabilities (for example the stewincu signal in systens derived from 4.3bsd), xterm will use the facilities to 
notify programs running in the window whenever it is resized. 


TheVT 102 and Tektronix 4014 terminals all have their own windows so that you can edit text in one and look at graphics 
in theother at thesame time To maintain the correct aspect ratio (height/width), T ektronix graphics will be restricted to the 
largest box with a 4014's aspect ratio that will fit in the window. T his box is located in the upper-left area of the window. 


Although both windows may be displayed at the same time, one of them is considered the active window for receiving 
keyboard input and terminal output. This is the window that contains thetext cursor. The active window can be chosen 
through escape sequences, the VT Options menu in the VT 102 window, and the T & Options menu in the 4014 window. 


EMULATIONS 


TheVT 102 emulation is fairly complete, but does not support smooth scrolling, VT 52 mode, the blinking character 
attribute nor the double wide and double-size character sets. termcap(5) entries that work with xterm include xterm, vt102, 
vt100, and ansi, and xterm automatically searches the termcap file in this order for these entries and then sets the Term and the 
TERMCAP environment variables. 


M any of the special xterm features may be modified under program control through a set of escape sequences different from 
the standard VT 102 escape sequences. (See the “Xterm Control Sequences” document.) 


TheT ektronix 4014 emulation is also fairly good. It supports 12-bit graphics addressing, scaled to the window size. Four 
different font sizes and five different lines types are supported. There is no write-through or defocused mode support. The 
Tektronix text and graphics commands are recorded internally by xterm and may be written to a file by sending the cory 
escape sequence (or through theT ektronix menu, discussed later in this section). The name of the file will be copyyy- mm- 
dd. hh: mm: ss, where y, MM, dd, hh, mm, and ssare the year, month, day, hour, minute, and second when the cory was 
performed (the file is created in the directory xterm is started in, or the home directory for alogin xterm). 


OTHER FEATURES 


xterm automatically highlights the text cursor when the pointer enters the window (sdected) and unhighlights it when the 
pointer leaves the window (unselected). | f the window is the focus window, then the text cursor is highlighted no matter 
where the pointer is. In VT 102 mode, there are escape sequences to activate and deactivate an alternate scren buffer, which 
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is the samesize as the display area of the window. When activated, the current screen is saved and replaced with the alternate 
screen. Saving of lines scrolled off the top of the window is disabled until the normal screm is restored. The termcap(5) entry 
for xterm allows the visual editor vi(1) to switch to the alternate screen for editing and to restore the screen on exit. 


In athe VT 102 or Tektronix mode, there are escape sequences to change the name of the windows. See xterm Control 


Sequences for details. 


OPTIONS 


The xterm terminal emulator accepts all of the standard X T oolkit command-line options as well as the following (if the 
option begins with a + instead of a -, the option is restored to its default value): 


-help 


-132 


-ah 


ah 


-b number 


-cb 
cb 


-cc characterclassrange: 


value[,...] 


-en 


cn 


-cr color 


-cu 


cu 


-e program 
[ arguments .. . ] 


-fb font 


This causes xterm to print out a verbose message describing its 
options. 
Normally, the VT 102 peccoLm escape sequence that switches 
between 80 and 132 column mode is ignored. T his option 
causes the DECCOLM escape sequence to be recognized, and the 
xterm window will resize appropriatdy. 

This option indicates that xterm should always highlight the 
text cursor. By default, xterm will display a hollow text cursor 
wheever the focus is lost or the pointer leaves the window. 
This option indicates that xterm should do text cursor 
highlighting based on focus. 

This option specifies the size of the inner border (the distance 
between the outer edge of the characters and the window 
border) in pixds. The default is 2. 

Se the vt100 resource cutToBeginningOfLine to False. 

Set the vt100 resource cutToBeginningOfLine tO True. 

This sets classes indicated by the given ranges to usein 
selecting by words. See the subsection “C haracter C lasses.” 
This option indicates that newlines should not be cut in line 
mode selections. 

This option indicates that newlines should be cut in linemode 
selections. 

This option specifies the color to use for text cursor. The 
default is to use the same foreground color that is used for text. 
This option indicates that xterm should work around a bug in 
the more(1) program that causes it to incorrectly display lines 
that are exactly the width of the window and are followed by a 
line beginning with a tab (the leading tabs are not displayed). 
This option is so named because it was originally thought to 
be a bug in the curses(3x) cursor motion package. 

This option indicates that xterm should not work around the 
more(3x) bug mentioned in the preceding paragraph. 

This option specifies the program (and its command-line 
arguments) to be run in the xterm window. It also sets the 
window title and icon name to be the basename of the 
program being executed if nather -T nor -n are given on 

the command line This must be the last option on the 
command line 

This option specifies a font to be used when displaying bold 
text. This font must be the same height and width as the 
normal font. If only one of the normal or bold fonts is 
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-im 


+im 


-ls 


Is 


-mb 


mb 


-memi || iseconds 
-ms color 


-nb number 


-rw 


rw 


-aw 


aw 


specified, it will be used as the normal font and the bold font 
will be produced by overstriking this font. T he default is to do 
overstriking of the normal font. 

Turn on theuseInsertMode resource. 

Turn off the useInsertMode resource. 

This option indicates that xterm should do jump scrolling. 
Normally, text is scrolled one lineat atime this option allows 
xterm to move multiple lines at a time so that it doesn’t fall as 
far behind. Its use is strongly recommended because it makes 
xterm much faster when scanning through large amounts of 
text. The VT 100 escape sequences for enabling and disabling 
smooth scroll as well asthe VT Options menu can be used to 
turn this feature on or off. 
This option indicates that xterm should not do jump scrolling. 
This option indicates that the shell that is started in the xterm 
window will bea login shell (that is, the first character of 
argv[0] will bea dash, indicating to the shell that it should 
read the user’s .login Or .profile). 

This option indicates that the shell that is started should not 
bea login shell (that is, it will be a normal subshdl). 

This option indicates that xterm should ring amargin bal 
when theuser types near the right end of aline This option 
can be turned on and off from the VT Optionsmenu. 

This option indicates that margin bell should not be rung. 
This option specifies the maximum time between multiclick 
selections. 
This option specifies the color to be used for the pointer 
cursor. T he default is to use the foreground color. 

This option specifies the number of characters from the right 
end of aline at which the margin bell, if enabled, will ring. 
The default is 10. 

This option indicates that reverse wraparound should be 
allowed. T his allows the cursor to back up from the leftmost 
column of one line to the rightmost column of the previous 
line Thisis very useful for editing long shell command lines 
and is encouraged. T his option can beturned on and off from 
theVT Optionsmenu. 

This option indicates that reverse-wraparound should not be 
allowed. 
This option indicates that auto-wraparound should be 
allowed. This allows the cursor to automatically wrap to the 
beginning of the next line when it isat the rightmost position 
of aline and text is output. 

This option indicates that auto-wraparound should not be 
allowed. 
This option indicates that xterm may scroll asynchronously, 
meaning that the screen does not have to be kept completely 
up to date while scrolling. This allows xterm to run faster when 
network latencies are very high and is typically useful when 
running across a very large Internet or many gateways. 
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s This option indicates that xterm should scroll synchronously. 

-sb This option indicates that some number of lines that are 
scrolled off the top of the window should be saved and that a 
scrollbar should be displayed so that those lines can be viewed. 
This option may beturned on and off from the VT Options 





menu. 

sb This option indicates that a scrollbar should not be displayed. 

-sf This option indicates that Sun Function K ey escape codes 
should be generated for function keys. 

st This option indicates that the standard escape codes should be 
generated for function keys. 

-si This option indicates that output to a window should not 


automatically reposition the screen to the bottom of the 
scrolling region. Thisoption can beturned on and off from 
theVT Optionsmenu. 





si This option indicates that output to a window should cause it 
to scroll to the bottom. 
-sk This option indicates that pressing a key while using the 


scrollbar to review previous lines of text should cause the 
window to be repositioned automatically in the normal 
position at the bottom of the scroll region. 


sk This option indicates that pressing a key while using the 
scrollbar should not cause the window to be repositioned. 

-sl number This option specifies the number of lines to save that have 
been scrolled off the top of the screen. T he default is 64. 

-t This option indicates that xterm should start in T ektronix 


mode rather than in VT 102 mode Switching between the 
two windows is done using theO ptions menus. 

t This option indicates that xterm should start in VT 102 mode. 

-tm string This option specifies a series of terminal setting keywords 
followed by the characters that should be bound to those 
functions, similar to the stty program. Allowable keywords 
include: intr, quit, erase, kill, eof, eol, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and Inext. Control 
characters may be specified as *char (for example, *c or *u) and 
“2 may be used to indicate delete. 

-tn name This option specifies the name of the terminal type to be set in 
the Term environment variable. T his terminal type must exist 
in the termcap(5) database and should have 1i# and co# entries. 








-ut This option indicates that xterm shouldn't write a record into 
the system log file /etc/utmp. 

ut This option indicates that xterm should write a record into the 
system log file /etc/utmp. 

-vb This option indicates that a visual bell is preferred over an 


audible one Instead of ringing the terminal bell whenever a 

















Ctrl+G is received, the window will be flashed. 
vb This option indicates that a visual bell should not be used. 
-wf This option indicates that xterm should wait for the window to 


be mapped the first time before starting the subprocess so that 
the initial terminal size settings and environment variables are 
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wf 


-Sccn 


correct. It is the application’s responsibility to catch subse 
quent terminal size changes. 

This option indicates that xterm show not wait before starting 
the subprocess. 


This option indicates that this window should receive console 
output. Thisis not supported on all systems. To obtain 
console output, you must be the owner of the console device, 
and you must have read and write permission for it. If you are 
running x under xam on the console screen, you may need to 
have the session startup and reset programs explicitly change 
the ownership of the console devicein order to get this option 
to work. 

This option specifies the last two letters of the name of a 
pseudo-terminal to use in slave mode, plus the number of the 
inherited file descriptor. The option is parsed "ssc%sc%d". This 
allows xterm to be used asan input and output channel for an 
existing program and issometimes used in specialized 
applications. 


The following command-line arguments are provided for compatibility with older versions. T hey may not be supported in 
the next release as the X T oolkit provides standard options that accomplish the same task. 


Sageom 


geom 


-T string 


-n string 


-w number 


This option specifies the preferred size and position of the 
Tektronix window. It is shorthand for specifying the 
*tekGeometry PeSOurce. 

This option specifies the preferred position of theicon 
window. It is shorthand for specifying the «iconGeometry 
resource. 
This option specifies the title for xterm’s windows. It is 
equivalent to -title. 
This option specifies the icon name for xterm’s windows. It is 
shorthand for specifying the *iconName resource, N ote that this 
is not the same as the toolkit option -name (see below). The 
default icon nameis the application name 

This option indicates that reverse video should be simulated by 
swapping the foreground and background colors. It is 
equivalent to -rv. 

This option specifies the width in pixes of the border 
surrounding the window. It is equivalent to -borderwidth or 
-bw. 














The following standard X Toolkit command-line arguments are commonly used with xterm: 


-bg color 


-bd color 


-bw number 


-fg color 


-fn font 


This option specifies the color to use for the background of the 
window. T he default is white. 

This option specifies the color to use for the border of the 
window. T he default is black. 

This option specifies the width in pixds of the border 
surrounding the window. 

This option specifies the color to use for displaying text. The 
default is black. 
This option specifies the font to be used for displaying normal 
text. The default is fixed. 














-name name 


-title string 


-fv 


-geometry geometry 


-display display 


-xrm resourcestring 


-iconic 


RESOURCES 
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This option specifies the application name under which 
resources are to be obtained, rather than the default executable 
filename. N ame should not contain . or * characters. 

This option specifies the window title string, which may be 
displayed by window managers if the user so chooses. The 
default title is the command line specified after the -e option, 
if any; otherwise the application name. 

This option indicates that reverse video should be simulated by 
swapping the foreground and background colors. 

This option specifies the preferred size and position of the 
VT102 window; see x(1). 

This option specifies the X server to contact; see x(1). 

This option specifies a resource string to be used. Thisis 
especially useful for setting resources that do not have separate 
command-line options. 

This option indicates that xterm should ask the window 
manage’ to start it as an icon rather than as thenormal 
window. 








The program understands all of the core X T oolkit resource names and classes as well as the following: 


iconGeometry (class IconGeometry) 


iconName (class IconName) 


termName (class TermName) 


title (class Title) 


ttyModes (class TtyModes) 


useInsertMode 
(class UseInsertMode) 


utmpInhibit (class UtmpInhibit) 


sunFunctionKkeys 
(class SunFunctionKeys) 


waitForMap (class WaitForMap) 


Specifies the preferred size and position of the application 
when iconified. It is not necessarily obeyed by all window 
managers. 

Specifies the icon name. T he default is the application name 
Specifies the teminal type name to be set in the TERM 
environment variable. 

Specifies a string that may be used by the window manager 
when displaying this application. 

Specifies a string containing terminal setting keywords and the 
characters to which they may be bound. Allowable keywords 
include intr, quit, erase, kill, eof, eol, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and Inext. Contro 
characters may be specified as *char (for example, *c or *u) and 
“2 may be used to indicate ddete This is very useful for 
overriding the default terminal settings without having to do 
an stty every time an xterm is started. 

Force use of insert mode by adding appropriate entries to the 
TERMCAP environment variable. T his is useful if the system 
termcap is broken. The default is False. 

Specifies whether or not xterm should try to record the user's 
terminal in /etc/utmp. 

Specifies whether or not Sun Function K ey escape codes 
should be generated for function keys instead of standard 
escape sequences. 

Specifies whether or not xterm should wait for the initial 
window map before starting the subprocess. T he default is 
false. 
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The following resources are specified as part of the vt100 widget (class vt100): 


allowSendEvents 
(class AllowSendEvents) 


alwaysHighlight 
(class AlwaysHighlight) 


appcursorDefault 
(class AppcursorDefault) 


appkeypadDefault 
(class AppkeypadDefault) 


autoWrap (class AutoWrap) 


bellSuppressTime 
(class BellSuppressTime) 


boldFont (class BoldFont) 


c132 (class C132) 


cutNewline 
(class CutNewline) 


cutToBeginningOfLine 
(class CutToBeginningOfLine) 


charClass (class CharClass) 


curses (class Curses) 


background 
(class Background) 
foreground 
(class Foreground) 


cursorColor 

(class Foreground) 
eightBitInput 

(class EightBitInput) 


Specifies whether or not synthetic key and button 

events (generated using the x protocol sendEvent request) 
should be interpreted or discarded. The default is False, 
meaning they are discarded. N ote that allowing such events 
creates a very large security hole. 


Specifies whether or not xterm should always display 

a highlighted text cursor. By default, a hollow text cursor is 
displayed whenever the pointer moves out of the window or 
the window loses the input focus. 


If true, the cursor keys are initially in application mode. 
The default is false. 


If true, the keypad keys are initially in application mode 
The default is false. 


Specifies whether or not auto-wraparound should be enabled. 
The default is true. 


Number of milliseconds after a bell command is sent during 
which additional bells will be suppressed. D efault is 200. If set 
non-zero, additional bells will also be suppressed until the 
server reports that processing of the first bell has been com- 
pleted; this feature is most useful with the visible bell. 


Specifies the name of the bold font to use instead of 
overstriking. 

Specifies whether or not the VT 102 peccoLm escape sequence 
should be honored. T he default is false. 


If false, triple-clicking to select a line does not 
include the Newline at the end of theline If true, the Newline 
is sdlected. The default is true. 


If false, triple-clicking to select a line sdects only from 

the current word forward. If true, the entire line is selected. 
The default is true. 

Specifies comma-separated lists of character class bindings of 
the form [1low-jhigh: value. T hese are used in determining 
which sets of characters should be treated the same when 
doing cut and paste. See the section on specifying character 
Classes. 

Specifies whether or not the last column bug in more(1) should 
be worked around. See the -cu option for details. The default 
iS false. 

Specifies the color to use for the background of the window. 
The default is white. 


Specifies the color to use for displaying text in the window. 
Setting the class name instead of the instance name is an easy 
way to have everything that would normally appear in the text 
color change color. The default is black. 


Specifies the color to use for the text cursor. The 
default is black. 


If true, metacharacters input from the keyboard are presented 
as a single character with the eighth bit turned on. If false, 
metacharacters are converted into a two-character sequence 
with the character itsdf preceded by ESC. The default is true. 











eightBitOutput 
class EightBitOutput) 


ont (class Font 
ont1 (class Font1) 
ont2 (class Font2) 
ont3 (class Font3) 
ont4 (class Font4) 


ont5 (class Font5) 








ont6 (class Font6) 
geometry (class Geometry) 


hpLowerleftBugCompat 
(class HpLowerleftBugCompat) 


internalBorder 

class BorderWidth) 
jumpScrol 
ass JumpScroll) 


fo) 


oginShel 
class LoginShell) 
marginBel 
class MarginBell) 
multiClickTime 

class MultiClickTime) 
multiScroll 
class MultiScroll) 








nMarginBell (class Column) 


pointerColor 
(class Foreground) 





pointerColorBackground 
(class Background) 
pointerShape 

(class Cursor) 
resizeGravity 

(class ResizeGravity) 


reverseVideo 
(class ReverseVideo) 
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Specifies whether or not aght-bit characters sent from the 
host should be accepted as is or stripped when printed. The 
default is true. 


Specifies the name of the normal font. T he default is fixed. 
Specifies the name of the first alternative font. 
Specifies the name of the second alternative font. 
Specifies the name of the third alternative font. 
Specifies the name of the fourth alternative font. 
Specifies the name of the fifth alternative font. 
Specifies the name of the sixth alternative font. 
Specifies the preferred size and position of the VT 102 
window. 

Specifies whether to work around a bug in H P’s xdb, which 
ignores termcap and always sends ESC F to moveto the lower- 
left corner. true Causes xterm to interpret ESC F as a request 
to move to the lower-left corner of the screen. T he default is 
false. 

Specifies the number of pixels between the characters and the 
window border. The default is 2. 

Specifies whether or not jump scroll should be used. The 
default is true. 

Specifies whether or not the shell to be run in the window 
should be started as alogin shall. The default is false. 
Specifies whether or not the ball should be run when the user 
types near the right margin. T he default is false. 

Specifies the maximum time in milliseconds between 
multiclick sdect events. The default is 250 milliseconds. 
Specifies whether or not scrolling should be done asynchro- 
nously. T he default is false. 

Specifies the number of characters from the right margin at 
which the margin bal should be rung, when enabled. 


Specifies the foreground color of the pointer. The default is 
XtDefaultForeground 

Specifies the background color of the pointer. The default is 
XtDefaultBackground 

Specifies the name of the shape of the pointer. T he default is 
xterm. 

Affects the behavior when the window is resized to be taller or 
shorter. Northwest specifies that the top line of text on the 
screen stay fixed. If the window is made shorter, lines are 
dropped from the bottom; if the window is made taller, blank 
lines are added at the bottom. T his is compatible with the 
behavior in R4. southwest (the default) specifies that the 
bottom line of text on the screen stay fixed. If the window is 
made taller, additional saved lines will be scrolled down onto 
the screen; if the window is made shorte,, lines will be scrolled 
off the top of the screen, and the top saved lines will be 
dropped. 

Specifies whether reverse video should be simulated. The 
default is false. 
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reverseWrap 

class ReverseWrap) 
saveLines 

class SaveLines) 
scrollBar 

class ScrollBar) 
scrollTtyOutput 
class ScrollCond) 


scrollKey 
class ScrollCond) 











scrollLines 
(class ScrollLines) 





signalInhibit 
(class SignalInhibit) 


tekGeometry 
(class Geometry) 


tekInhibit 
(class TekInhibit) 


tekSmall (class TekSmall) 


tekStartup 

(class TekStartup) 
titeInhibit 

(class TiteInhibit) 


translations 
(class Translations) 


visualBell 
(class VisualBell) 


Specifies whether or not reverse-wraparound should be 
enabled. T he default is false. 

Specifies the number of lines to save beyond the top of the 
screen when a scrollbar is turned on. The default is 64. 
Specifies whether or not the scrollbar should be displayed. 
The default is false. 

Specifies whether or not output to theterminal should 
automatically cause the scrollbar to go to the bottom of the 
scrolling region. T he default is true. 

Specifies whether or not pressing a key should automatically 
cause the scrollbar to go to the bottom of the scrolling region. 
The default is false. 

Specifies the number of lines that the scroll-back and scroll- 
forw actions should use as a default. T he default value is 1. 
Specifies whether or not the entries in the M ain O ptions menu 
for sending signals to xterm should be disallowed. T he default 
iS false. 
Specifies the preferred size and position of the T ektronix 
window. 

Specifies whether or not the escape sequence to enter 
Tektronix mode should be ignored. T he default is false. 
Specifies whether or not the T ektronix mode window should 
start in its smallest size if no explicit geometry is given. Thisis 
useful when running xterm on displays with small screens. The 
default is false. 

Specifies whether or not xterm should start up in T ektronix 
mode The default is false. 

Specifies whether or not xterm should remove ti and te 
termcap entries (used to switch betwee alternate screens on 
startup of many screen-oriented programs) from the TerMcaP 
string. If set, xterm also ignores the escape sequence to switch 
to the alternate screen. 

Specifies the key and button bindings for menus, selections, 
“orogrammed strings,” and so on. Seethe “ACTIONS” 
subsection, later in this section. 

Specifies whether or not a visible bell (that is, flashing) should 
be used instead of an audible bell when C ontrol-G is received. 
The default is false. 








The following resources are specified as part of the tek4o14 widget (class Tek4014): 


width (class Width) 

height (class Height) 

fontLarge (class Font) 

font2 (class Font) 

font3 (class Font) 

fontSmall (class Font) 
initialFont (class InitialFont) 


ies the width of theT ektronix window in pixels. 
ies the height of the T ektronix window in pixds. 
ies the large font to use in the T ektronix window. 
ies font number 2 to usein the T ektronix window. 
Specifies font number 3 to usein the Tektronix window. 
Specifies the small font to use in the T ektronix window. 


Specifies which of the four T ektronix fonts to use initially. 
Values are the sameas for the set-tek-text action. The default 
iS large. 


Speci 
Speci 
Speci 


fi 
fi 
fi 
Specif 
fi 
fi 
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Specifies what character(s) should follow a GIN 

report or status report. T he possibilities are none, which sends 
no terminating characters, cRonly, which sends cr, and cr&eoT, 
which sends both cr and Eor. T he default isnone 


ginTerminator 
(class GinTerminator) 


The resources that may be specified for the various menus are described in the documentation for the Athena simp1emenu 
widget. The name and classes of the entries in each of the menus are listed next. 


The mainMenu has the following entries: 





securekbd (class SmeBSB) This entry invokes the secure() action. 

allowsends (class SmeBSB) This entry invokes the allow-send-events(toggle) action. 

redraw (class SmeBSB) This entry invokes the redraw() action. 

line1 (class SmeLine) This is a separator. 

suspend (class SmeBSB) This entry invokes the send-signal(tstp) action on systems 
that support job control. 

continue (class SmeBSB) This entry invokes the send-signal(cont) action on systems 
that support job control. 

interrupt (class SmeBSB) This entry invokes the send-signal(int) action. 

hangup (class SmeBSB) This entry invokes the send-signal(hup) action. 

terminate (class SmeBSB) This entry invokes the send-signal(term) action. 

kill (class SmeBSB) This entry invokes the send-signal(kill) action. 

line2 (class SmeLine) This is a separator. 

quit (class SmeBSB) This entry invokes the quit() action. 


The vtmenu has the following entries: 











scrollbar (class SmeBSB) This entry invokes the set-scrollbar (toggle) action. 
jumpscroll (class SmeBSB) This entry invokes the set -jumpscroll(toggle) action. 
reversevideo (class SmeBSB) This entry invokes the set -reverse-video(toggle) action. 
autowrap (class SmeBSB) This entry invokes the set -autowrap(toggle) action. 
reversewrap (class SmeBSB) This entry invokes the set -reversewrap(toggle) action. 
autolinefeed (class SmeBSB) This entry invokes the set -autolinefeed(toggle) action. 
appcursor (class SmeBSB) This entry invokes the set -appcursor (toggle) action. 
appkeypad (class SmeBSB) This entry invokes the set -appkeypad (toggle) action. 
scrollkey (class SmeBSB) This entry invokes the set-scroll-on-key(toggle) action. 
scrollttyoutput This entry invokes the set -scroll-on-tty-output (toggle) 
(class SmeBSB) action. 

allow132 (class SmeBSB) This entry invokes the set -allow132(toggle) action. 
cursesemul (class SmeBSB) This entry invokes the set -cursesemul(toggle) action. 
visualbell (class SmeBSB) This entry invokes the set -visualbell(toggle) action. 
marginbell (class SmeBSB) This entry invokes the set -marginbell(toggle) action. 
altscreen (class SmeBSB) This entry is currently disabled. 

line1 (class SmeLine) This is a separator. 

softreset (class SmeBSB) This entry invokes the soft-reset() action. 

hardreset (class SmeBSB) This entry invokes the hard-reset() action. 
clearsavedlines (class SmeBSB) " This entry invokes the clear-saved-lines() action. 

line2 (class SmeLine) This is a separator. 

tekshow (class SmeBSB) This entry invokes the set -visibility(tek, toggle) action. 
tekmode (class SmeBSB) This entry invokes the set-terminal-type(tek) action. 
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vthide (class SmeBSB) This entry invokes the set-visibility(vt, off) action. 

T he fontmenu has the following entries: 

ontdefault (class SmeBSB) This entry invokes the set-vt-font(d) action. 

ont1 (class SmeBSB) This entry invokes the set-vt-font(1) action. 

ont2 (class SmeBSB) This entry invokes the set -vt-font(2) action. 

ont3 (class SmeBSB) This entry invokes the set -vt-font(3) action. 

ont4 (class SmeBSB) This entry invokes the set-vt-font(4) action. 

ont5 (class SmeBSB) This entry invokes the set-vt-font(5) action. 

ont6 (class SmeBSB) This entry invokes the set-vt-font(6) action 

ontescape (class SmeBSB) This entry invokes the set-vt-font(e) action. 

ontsel (class SmeBSB) This entry invokes the set-vt-font(s) action. 

T he tekmenu has the following entries: 

tektextlarge (class SmeBSB) This entry invokes the set-tek-text(1) action. 

tektext2 (class SmeBSB) This entry invokes the set-tek-text(2) action. 

tektext3 (class SmeBSB) This entry invokes the set-tek-text(3) action. 
tektextsmall (class SmeBSB) This entry invokes the set-tek-text(s) action. 

linet (class SmeLine) This is a separator. 

tekpage (class SmeBSB) This entry invokes the tek-page() action. 

tekreset (class SmeBSB) This entry invokes the tek-reset() action. 

tekcopy (class SmeBSB) This entry invokes the tek-copy() action. 

line2 (class SmeLine) This is a separator. 

vtshow (class SmeBSB) This entry invokes the set-visibility(vt,toggle) action. 
vtmode (class SmeBSB) This entry invokes the set-terminal-type(vt) action. 
tekhide (class SmeBSB) This entry invokes the set-visibility(tek, toggle) action. 
T he following resources are useful when specified for the Athena Scrollbar widget: 

thickness (class Thickness) Specifies the width in pixels of the scrollbar. 

background (class Background) Specifies the color to use for the background of the scrollbar. 
foreground (class Foreground) Specifies the color to use for the foreground of the scrollbar. 


The “thumb” of the scrollbar is a simple checkerboard pattern 
alternating pixels for foreground and background color. 


POINTER USAGE 
Oncethe VT 102 window is created, xterm allows you to sdect text and copy it within the same or other windows. 


The selection functions are invoked when the pointer buttons are used with no modifiers, and when they are used with the 
Shift key. The assignment of the functions described in this subsection to keys and buttons may be changed through the 
resource database; see the “Actions” subsection later in this section. 


Pointer button one (usually left) is used to save text into the cut buffer. M ove the cursor to the beginning of thetext, and 
then hold the button down while moving the cursor to the end of the region and releasing the button. The selected text is 
highlighted and is saved in the global cut buffer and made the primary selection when the button is released. D ouble-clicking 
selects by words. T riple-clicking sects by lines. Q uadruple-clicking goes back to characters, and so on. M ultiple-click is 
determined by thetime from button up to button down, so you can change the sdection unit in the middle of aselection. If 
the key/button bindings specify that an X selection is to be made, xterm will leave the sdected text highlighted for aslong as 
it isthe selection owner. 
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Pointer button two (usually middle) “types” (pastes) the text from the primary selection, if any, otherwise from the cut 
buffer, inserting it as keyboard input. 


Pointer button three (usually right) extends the current selection. (Without loss of generality, you can swap “right” and “left” 
everywhere in the rest of this paragraph.) | f pressed while closer to the right edge of the selection than the left, it extends/ 
contracts the right edge of the sdection. If you contract the sdection past the left edge of the selection, xterm assumes you 
really meant the left edge, restores the original sdection, then extends/contracts the left edge of the sdection. Extension starts 
in the selection unit mode that the last selection or extension was performed in; you can multiple-click to cycle through 
them. 


By cutting and pasting pieces of text without trailing new lines, you can take text from several places in different windows 

and form acommand to the shell, for example, or take output from a program and insert it into your favorite editor. Since 
the cut buffer is globally shared among different applications, you should regard it as a file whose contents you know. The 
terminal emulator and other text programs should be treating it as if it were a text file, that is, the text isddimited by new 

lines. 


The scroll region displays the position and amount of text currently showing in the window (highlighted) relative to the 
amount of text actually saved. As more text is saved (up to the maximum), the size of the highlighted area decreases. 


Clicking button onewith the pointe in the scroll region moves the adjacent line to the top of the display window. 
Clicking button three moves the top line of the display window down to the pointer position. 


Clicking button two moves the display to a position in the saved text that corresponds to the pointe’’s position in the 
scrollbar. 


Unlike the VT 102 window, theT ektronix window does not allow the copying of text. It does allow T ektronix GIN mode, 
and in this mode the cursor will change from an arrow to across. Pressing any key will send that key and the current 
coordinate of the cross cursor. Pressing button one two, or three will return the letters 1, m, and r, respectively. If the Shift 
key is pressed when a pointer button is pressed, the corresponding uppercase letter is sent. T 0 distinguish a pointer button 
from akey, the high bit of the character is set (but thisis bit is normally stripped unless the terminal mode is RAW; see 
tty(4) for details). 


MENUS 


xterm has four menus: mainMenu, vtMenu, fontMenu, and tekMenu. Each menu pops up under the correct combinations of key 
and button presses. M ost menus are divided into two sections, separated by a horizontal line. The top portion contains 
various modes that can be altered. A check mark appears next to a mode that is currently active Selecting one of these modes 
toggles its state. The bottom portion of the menu consists of command entries; selecting one of these performs the indicated 
function. 


The xterm menu popsup when the Control key and pointer button one are pressed in a window. T he mainwenu contains 
itans that apply to both the VT 102 and T ektronix windows. T he Secure K eyboard mode is used when typing in passwords 
or other sensitive data in an unsecured environment. (See the “SECURITY” subsection.) N otable entries in the command 
section of the menu are the Continue, Suspend, Interrupt, H angup, Terminate and Kill, which send thesteconT, siaTsTP, 
SIGINT, SIGHUP, SIGTERM, aNd SIGKILL signals, respectively, to the process group of the process running under xterm (usually 
the shell). The Continue function is especially useful if the user has accidentally typed CTRL-Z, suspending the process. 


The vtmenu sets various modes in the VT 102 emulation, and is popped up when the Control key and pointer button two are 
pressed in the VT 102 window. In the command section of thismenu, the Soft Reset entry will reset scroll regions. T his can 
be convenient when some program has left the scroll regions set incorrectly (often a problen when using VMS or TO PS-20). 
The Full Reset entry will clear the screen, reset tabs to every aight columns, and reset the terminal modes (such as wrap and 
smooth scroll) to their initial states just after xterm has finished processing the command-line options. 


The fontmenu sets the font used in the VT 102 window. In addition to the default font and anumber of alternatives that are 
set with resources, the menu offers the font last specified by the Set Font escape sequence (see the document “Xterm Control 
Sequences”) and the current sdection as a font name (if the prrmary selection is owned). 
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The tekmenu sets various modes in the T ektronix emulation, and is popped up when the Control key and pointer button two 
are pressed in the T ektronix window. T he current font size is checked in the M odes section of the menu. The pace entry in 
the Command section clears the T ektronix window. 


SECURITY 


X environments differ in their security consciousness. M ost servers, run under xdm, are capable of using a “magic cookie” 
authorization schene that can provide a reasonable level of security for many people. If your server is only using a host-based 
mechanism to control access to the server (see xhost(1)), then if you enable access for a host and other users are also 
permitted to run clients on that same host, there is every possibility that someone can run an application that will use the 
basic services of the x protocol to snoop on your activities, potentially capturing a transcript of everything you type at the 
keyboard. This is of particular concern when you want to type in a password or other sensitive data. T he best solution to this 
problem is to use a better authorization mechanism that host-based control, but a simple mechanism exists for protecting 
keyboard input in xterm. 


The xterm menu (see “M enus,” earlier in this section) contains a Secure Keyboard entry which, when enabled, ensures that all 
keyboard input is directed only to xterm (using the GrabKeyboard protocol request). When an application prompts you for a 
password (or other sensitive data), you can enable secure Keyboard using the menu, type in the data, and then disable secure 
Keyboard using the menu again. Only one xX client at a timecan secure the keyboard, so when you attempt to able secure 
Keyboard, it may fail. In this case, the ball will sound. If the secure Keyboard succeeds, the foreground and background colors 
will be exchanged (as if you selected the Reverse Video entry in the M odes menu); they will be exchanged again when you 
exit secure mode If the colors do not switch, then you should be very suspicious that you are being spoofed. If the applica- 
tion you are running displays a prompt before asking for the password, it is safest to enter secure mode before the prompt 
gets displayed, and to make sure that the prompt gets displayed correctly (in the new colors), to minimize the probability of 
spoofing. You can also bring up the menu again and make sure that a check mark appears next to the entry. 


Secure K eyboard mode will be disabled automatically if your xterm window becomes iconified (or otherwise unmapped), or 
if you start up a reparenting window manager (that places a title bar or other decoration around the window) whilein Secure 
Keyboard mode. (Thisis a feature of the x protocol that isn’t easily overcome.) When this happens, the foreground and 
background colors will be switched back and the bell will sound in warning. 


CHARACTER CLASSES 


Clicking the middle mouse button twice in rapid succession will cause all characters of thesame class (for example, letters, 
whitespace, punctuation) to be sdected. Since different people have different preferences for what should be selected (for 
example, should filenames be selected as a whole or only the separate subnames?), the default mapping can be overridden 
through the use of the charClass (class CharClass) resource 


This resource is a series of comma-separated range: val ue pairs. The range is ather a single number or low-high in the range 
of 0 to 127, corresponding to the ASCII code for the character or characters to be set. The value is arbitrary, although the 
default table uses the character number of the first character occurring in the set. 


The default table is 


static int charClass[128] = { 

/* NUL SOH STX ETX EOT ENQ ACK BEL */ 
82 A Asay Ty ete; 

/* BS HT NL VT NP CR SO SI */ 

1908 AS SH. Migs eT 

/* DLE DC1 DC2 DC3 DC4 NAK SYN ETB */ 
te Ai Aig Aye hs, Vy 15 

/* CAN EM SUB ESC FS GS RS US */ 
Pee eA tae 

/*SP!"#$%& ' */ 

$2, 33, 34,85, 96, 37, 8B, 39, 
[*()*t,-./%*/ 

40, 41, 42, 43, 44, 45, 46, 47, 
17012345 67 */ 
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48, 48, 48, 48, 48, 48, 48, 48, 
1*8 9 :3< => 2*/ 

48, 48, 58, 59, 60, 61, 62, 63, 
/*@ABC D E F G*/ 

64, 48, 48, 48, 48, 48, 48, 48, 
/*HIJKLMNO */ 

48, 48, 48, 48, 48, 48, 48, 48, 
/*P QR S T UVW*/ 

48, 48, 48, 48, 48, 48, 48, 48, 
/*XY Z [\]> */ 

48, 48, 48, 91, 92, 93, 94, 48, 
/*'ab cde fg */ 

96, 48, 48, 48, 48, 48, 48, 48, 
/*h ijklm no */ 

48, 48, 48, 48, 48, 48, 48, 48, 
/*p qrs tu v w */ 

48, 48, 48, 48, 48, 48, 48, 48, 
/*x y zf jg” DEL */ 

48, 48, 48, 123, 124, 125, 126, 1}; 


For example, the string 33:48, 37:48 ,45-47:48,64:48 indicates that the exclamation mark, percent sign, dash, period, slash, 


and ampersand characters should be treated the same way as characters and numbers. T his is useful for cutting and pasting 
electronic mailing addresses and filenames. 


ACTIONS 


It is possible to rebind keys (or sequences of keys) to arbitrary strings for input by changing the translations for the vt10e or 
tek4014 widgets. Changing the translations for events other than key and button events is not expected, and will cause 
unpredictable behavior. T he following actions are provided for using within the vt100 or tek4o14 translations resources: 











bell([percent ]) This action rings the keyboard bell at the specified percentage 
above or bdow the base volume. 

ignore() This action ignores the event but checks for special pointer 
position escape sequences. 

insert() This action inserts the character or string associated with the 
key that was pressed. 

insert-seven-bit() This action isa synonym for insert(). 

insert-eight-bit() This action inserts an eight-bit (M eta) version of the character 
or string associated with the key that was pressed. T he exact 
action depends on the value of the eightBitInput resource. 

insert-selection This action inserts the string found in theselection or cut 

(sourcename [, ...]) buffer indicated by sourcename. Sources are checked in 


the order given (case is significant) until oneis found. 
Commonly used selections include PRIMARY, SECONDARY, and 
CLIPBOARD. C ut buffers are typically named cuT_BUFFERO 
through cuT_BUFFER7. 

keymap (name ) This action dynamically defines a new translation table whose 
resource name is name with the suffix Keymap (case is signifi- 
cant). The name none restores the original translation table 


popup -menu(menuname ) This action displays the specified pop-up menu. Valid names 
(case is significant) include mainMenu, vtMenu, fontMenu, and 
tekMenu. 

secure() This action toggles the Secure K eyboard mode described in the 


“Security” subsection, and isinvoked from the securekbd entry 
in mainMenu. 
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select-start() 


select-extend () 


select-end 
(destname [, ...]) 


select-cursor-start() 





select -cursor-end 
(destname [, ...]) 


set -vt-font 
(d/1/2/3/4/5/6/e/s 
[, normalfont [, boldfont ]]) 


start-extend() 


start-cursor -extend() 


string(string) 


scroll-back(count [,units]) 


scroll-forw(count [,units]) 
allow-send-events 
(on/off/ toggle) 


redraw() 


send-signal(si gname ) 


quit() 


This action begins text sdection at the current pointer 
location. See the subsection on “Pointer U sage” for informa 
tion on making sdections. 

This action tracks the pointer and extends the selection. It 
should only be bound to M otion events. 

This action puts the currently selected text into all of the 
selections or cut buffers specified by dest name. 

This action is similar to select-start except that it begins the 
selection at the current text cursor position. 

This action is similar to select-end except that it should 

be used with select-cursor-start. 

This action sets the font or fonts currently being 

used in theVT 102 window. Thefirst argument isa 

single character that specifies the font to be used: d orp 
indicate the default font (the font initially used when xterm 
was started), 1 through 6 indicate the fonts specified by the 
font1 through fonté resources, e or E indicatethe normal and 
bold fonts that have been set through escape codes (or 
specified as the second and third action arguments, respec- 
tively), ands ors indicate the font selection (as made by 
programs such as xfontse1(1)) indicated by the second action 
argument. 
This action is similar to select-start except that the sdection 
is extended to the current pointer location. 


This action is similar to select-extend except that the selection 
is extended to the current text cursor position. 

This action inserts the specified text string as if it had been 
typed. Quotation is necessary if the string contains whitespace 
or nonalphanumervic characters. If the string argument begins 
with the characters ox, it is interpreted as a hex character 
constant. 

This action scrolls the text window backward so that text that 
had previously scrolled off the top of the screen is now visible 
Thecount argument indicates the number of units (which 
may be page, half page, pixel, or line) by which to scroll. 

This action scroll is similar to scro11-back except that it scrolls 
the other direction. 


This action set or toggles the allowSendEvents resource and is 
also invoked by the allowsends entry in mainMenu. 

This action redraws the window and is also invoked by the 
redraw entry in mainMenu. 

This action sends the signal named by si gname to the xterm 
subprocess (the shell or program specified with the -e 
command-line option) and is also invoked by the suspend, 
continue, interrupt, hangup, terminate, and kill entriesin 
mainMenu. Allowable signal names are (case is not significant) 
tstp (if supported by the operating systen), suspend (Same as 
tstp), cont (if Supported by the operating system), int, hup, 
term, quit, alrm, alarm (Same aS alrm), and kill. 

This action sends a stcHup to the subprogram and exits. It is 
also invoked by the quit entry in mainMenu. 











set- 


se 


ct 


set- 


set 


set- 


set- 


se 


ct 


se 


ta 


set 


set- 


set- 


set- 


set 


set 


set- 


scrollbar (on/off/toggle) 


-jumpscroll(on/off/toggle) 


reverse-video(on/off/toggle) 


-autowrap(on/off/toggle) 


reversewrap(on/off/toggle) 


autolinefeed(on/off/toggle) 


-appcursor(on/off/toggle) 


-appkeypad(on/off/toggle) 


-scroll-on-key(on/off/toggle) 


scroll-on-tty-output(on/off/toggle) 


allow132(on/off/toggle) 


cursesemul(on/off/toggle) 


-visual-bell(on/off/toggle) 


-marginbell(on/off/toggle) 


altscreen(on/off/toggle) 


soft-reset() 


hard-reset() 


clear -saved-lines() 


set- 


terminal-type(type ) 


set-visibility(vt/tek, on/off/toggle) 


set-tek-text(large/2/3/small ) 


tek- 


page () 
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This action toggles the scrollbar resource and is also invoked 
by the scrollbar entry in vtMenu. 

This action toggles the jumpscro11 resource and is also invoked 
by the jumpscro11 entry in vtMenu. 

This action toggles the reverseVideo resource and is also 
invoked by the reversevideo entry in vtMenu. 

This action toggles automatic wrapping of long lines and is 
also invoked by the autowrap entry in vtMenu. 

This action toggles the reversewrap resource and is also 
invoked by the reversewrap entry in vtMenu. 

This action toggles automatic insertion of line-feeds and is also 
invoked by the autolinefeed entry in vtMenu. 

This action toggles the handling Application C ursor K ey mode 
and is also invoked by the appcursor entry in vtMenu. 

This action toggles the handling of Application K ey-pad mode 
and is also invoked by the appkeypad entry in vtMenu. 

This action toggles the scrollkey resource and is also 

invoked from the scrollkey entry in vtMenu. 

This action toggles the scrollTtyoutput resource and is also 
invoked from the scrollttyoutput entry in vtMenu. 

This action toggles the c132 resource and is also invoked from 
the allow132 entry in vtMenu. 
This action toggles the curses resource and is also invoked 
from the cursesemul entry in vtMenu. 
This action toggles the visualBel1 resource and is also invoked 
by the visualbe11 entry in vtMenu. 
This action toggles the marginBell resource and is also invoked 
from the marginbe11 entry in vtMenu. 


This action toggles between the alternate and current screens. 
This action resets the scrolling region and is also invoked from 
the softreset entry in vtMenu. 

This action resets the scrolling region, tabs, window size and 
cursor keys, and clears the screen. It is also invoked from the 
hardreset entry in vtMenu. 


This action does hard-reset() and also clears the history of 
lines saved off the top of the screen. It is also invoked from the 
clearsavedlines entry in vtMenu. 

This action directs output to either the vt or tek windows, 
according to thet ype string, It is also invoked by the tekmode 
entry in vtMenu and the vtmode entry in tekMenu. 

This action controls whether or not the vt or tek windows 

are visible It is also invoked from the tekshow and vthide 
entriesin vtMenu and the vtshow and tekhide entries in tekMenu. 
This action sets font used in the T ektronix window to 

the value of the resources tektextlarge, tektext2, tektext3, 
and tektextsmall according to the argument. It is also 

by the entries of thesame names as the resources in tekMenu. 
This action clears the T ektronix window and isalso invoked 
by the tekpage entry in tekMenu. 
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tek-reset() 


tek-copy() 


visual-bell() 


TheT ektronix window also has the following action: 


gin-press(I/L/m/M/r/R) 


The default bindings in the VT 102 window are 


Shift <KeyPress> Prior: scroll-back(1,halfpage) \n\ 
Shift <KeyPress> Next: scroll-forw(1,halfpage) \n\ 
Shift <KeyPress> Select: select-cursor-start() \ 
select-cursor-end(PRIMARY, CUT _BUFFERQ) \n\ 

Shift <KeyPress> Insert: insert-selection(PRIMARY, CUT _BUFFERQ) \n\ 
“Meta<KeyPress>: insert-seven-bit() \n\ 
Meta<KeyPress>: insert-eight-bit() \n\ 

!Ctrl <BtniDown>: popup-menu(mainMenu) \n\ 

Ctrl <BtniDown>: popup-menu(mainMenu) \n\ 

Ctrl <BtniDown>: popup-menu(mainMenu) \n\ 

Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 
<BtniDown>: select-start() \n\ 

<BtniMotion>: select-extend() \n\ 

<Btn2Down>: popup-menu(vtMenu) \n\ 

Ctrl <Btn2Down>: popup-m 


!Lock 
!Mod2 
!Mod2 
“Meta 
“Meta 
{Ctrl 
!Lock 


The default bindings in the T ektronix window are 


“Meta<KeyPress>: insert-seven-bit() \n\ 
Meta<KeyPress>: insert-eight-bit() \n\ 
<BtniDown>: popup-menu(mainMenu) \n\ 


!Ctr 
!Lock 
!Mod2 
!Mod2 
!Ctr 
!Lock 
!Mod2 
!Mod2 
Shif 


Ctr 
Ctr 


<Btn1Down>: popup-menu(mainMenu) \n\ 
<Btn1Down>: popup-menu(mainMenu) \n\ 


Lock Ctrl <BtniDown>: popup-menu(mainMenu) \n\ 
<Btn2Down>: popup-menu(tekMenu) \n\ 


Ctr 
Ctr 


<Btn2Down>: popup-menu(tekMenu) \n\ 
<Btn2Down>: popup-menu(tekMenu) \n\ 


Lock Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 


Me 


a<BtniDown>: gin-press(L) \n\ 


“Meta<BtniDown>: gin-press(1) \n\ 


Shif 


Me 





a<Btn2Down>: gin-press(M) \n\ 


“Meta<Btn2Down>: gin-press(m) \n\ 





Shif 


Me 





a<Btn3Down>: gin-press(R) \n\ 


“Meta<Btn3Down>: gin-press(r) 


This action resets the T ektronix window and is also invoked 
by the tekreset entry in tekMenu. 

This action copies the escape codes used to generate the 
current window contents to a file in the current directory 
beginning with the namecoprv. It is also invoked from the 
tekcopy entry in tekMenu 


This action flashes the window quickly. 


This action sends the indicated graphics input code. 


Bdow is a sample how of the keymap() action is used to add special keys for entering commonly typed works: 


*VT100.Translations: #override <Key>F13: keymap(dbx) 
VT100.dbxKeymap.translations: \ 

<Key>F14: 
<Key>F17: 
<Key>F18: 
<Key>F19: 
<Key>F20: 


keymap(None) \n\ 

string("next") string(@x@d) \n\ 
string("step") string(@x0d) \n\ 
string("continue") string(@x@d) \n\ 


string("print ") insert-selection(PRIMARY, CUT_BUFFERQ) 
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ENVIRONMENT 
xterm sets the environment variables Term and TerwcaP properly for the size window you have created. It also uses and sets the 
environment variable prsPLay to specify which bit map display terminal to use. The environment variable winpowrp is set to 
the X window id number of the xterm window. 

SEE ALSO 
resize(1), x(1), pty(4), tty(4) 
Xterm Control Sequences 


BUGS 


Large pastes do not work on some systems. Thisisnot a bug in xterm; it isa bug in the pseudo-terminal driver of those 
systems. xterm feeds large pastes to thepty only as fast as the pty will accept data, but some pty drivers do not return enough 
information to know if the write has succeeded. 


M any of the options are not resettable after xterm starts. 
Only fixed-width, character-cell fonts are supported. 


This program still needs to be rewritten. It should be split into very modular sections, with the various emulators being 
completely separate widgets that don’t know about each other. Ideally, you'd like to be able to pick and choose emulator 
widgets and stick them into asingle control widget. 


There needs to be a dialog box to allow entry of the T ek cory filarame. 


AUTHORS 


Far too many people, including Loretta Guarino Reid (DEC-UEG-WSL), Joel M cCormack (D EC-UEG-W SL), Terry 
Weissman (D EC-UEG-WSL), Edward M oy (Berkeley), Ralph R. Swick (MIT -Athena), M ark Vandevoorde (M IT -Athena), 
Bob M cNamara(DEC-M AD), Jim Gettys (MIT-Athena), Bob Schefler (MIT X Consortium), Doug Mink (SAO), Steve 
Pitschke (Stdlar), Ron Newman (MIT -Athena), Jim Fulton (MIT X Consortium), D ave Serisky (H P), Jonathan K amens 
(M IT-Athena) 
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Xvfb— Virtual framebuffer X server for X Version 11 


SYNOPSIS 


Xvfb [ option]... 


DESCRIPTION 


Xvfb iS an X server that can run on machines with no display hardware and no physical input devices. It enulates a dumb 
framebuffer using virtual memory. 


The primary use of this server is intended to be server testing. Themfb or cfb code for any depth can be exercised with this 
server without the need for real hardware that supports the desired depths. 


A secondary use is testing clients against unusual depths and screen configurations. 
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OPTIONS 


In addition to the normal server options described in the xserver(1) manual page, xvfb accepts the following command-line 


switches: 


-screen screennum WxHxD 


-pixdepths list-of-depths 


-fbdir framebuffer-directory 


-shmem 


This option creates screen screennum and sets its width, height, 
and depth to w, H, and p, respectively. By default, only screen 0 
exists and has the dimensions 1280x1024x8. 

This option specifies a list of pixmap depths that the server 
should support in addition to the depths implied by the 
supported screens. list -of -depths is a space-separated list of 
integers that can have values from 1 to 32. 

This option specifies the directory in which the memory- 
mapped files containing the framebuffer menory should be 
created. (See “Files.”) This option only exists on machines that 
have the mmap and msync system calls. 

This option specifies that the framebuffer should be put in 
shared memory. The shared memory ID for each screen will be 
printed by the server. The shared memory is in xwd format. 
This option only exists on machines that support the System V 
shared memory interface. 


If neither -shmem nor -fbdir is specified, the framebuffer memory will be allocated with malloc(). 


FILES 


The following file is created if the -fbdir option is given: 


framebuffer-directory 
/Xvfb_screen<n> 


EXAMPLES 


Xvfb :1 -screen @ 1600x1200x32 


Xvfb :1 -screen 1 1600x1200x16 


Xvfb -pixdepths 3 27 
-fbdir /usr/tmp 


xwud -in /usr/tmp/Xvfb screend 


SEE ALSO 


X(1), Xserver(1), xwd(1), xwud(1), xWOFile.h 


AUTHORS 
David P. Wiggins(X Consortium, Inc.) 


M emory-mapped file containing screen n’s framebuffer 
memory, onefile per screen. The file is in xwd format. 


The server will listen for connections as server number 1, and 
screen 0 will be deoth 32 1600x1200. 

The server will listen for connections as server number 1, will 
have the default screen configuration (one screen, 
1280x1024x8), and screen 1 will bedepth 16 1600x1200. 
Theserver will listen for connections as server number 0, 

will have the default screen configuration (one screen, 
1280x1024xé8), will also support pixmap depths of 3 and 27, 
and will use memory-mapped filesin /usr/tmp for the 
framebuffer. 

Displays screen 0 of the server started by the preceding 
example. 
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xvidtune 


xvidtune— Video mode tuner for XF ree86 


SYNOPSIS 


xvidtune [ -prev j -next j -unlock j -query j -saver suspendtime [ offtime ]][-toolkitoption ... ] 


DESCRIPTION 
Xvidtune isa client interface to the X Free86 X server video mode extension (X Free86-V idM odeE xtension), 


W hen given one of the nontoolkit options, xvidtune provides a command-line interface to either switch the video mode or 
get/set monitor powersaver time-outs. 


W ithout any options (or with only toolkit options) it presents the user with various buttons and sliders that can be used to 
interactively adjust existing video modes. It will also print the settings in a format suitable for inclusion in an xF8écontig file. 


NOTE 


The original mode settings can be restored by pressing ther Key, and thiscan be used to restore a stable screen in situa- 
tions where the screen becomes unreadable. 


The available buttons are 

Left 

Right 

Up 

Down 

Adjust the video mode so that the display will be moved in the appropriate direction: 
Wider 

Narrower 

Shorter 

Taller 


Adjust the video mode so that the display sizeis altered appropriatay: 


Quit Exit the program. 
Apply Adjust the current video modeto match the selected settings. 
Auto Cause the U p/D own/Right/Left, W ider/N arrower/Shorte/ 


Taller, Restore and the special S3 buttons to be applied 
immediately. This button can be toggled. 


Test Temporarily switch to the selected settings. 

Restore Return the settings to ther original values. 

Fetch Query the server for its current settings. 

Show Print the currently selected settings to stdout in xF86Config 
Modeline format. The primary selection is similarly set. 

Next Switch the xserver to thenext video mode. 

Prev Switch the xserver to the previous video mode. 


For some S3-based cards (964 and 968) the following are also available 


InvertVCLK Change the VCLK invert/noninvet state. 
EarlySC Change the Early SC state. This affects screen wrapping. 
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BlankDelay1, BlankDelay2 Se the blank delay values. T his affects screen wrapping. 
Acceptable values are in the range 0-7. T he values may be 
incremented or decremented with the +and - buttons, or by 
pressing the +or - keysin the text field. 


For S3-864/868 based cards, InvertVCLK and BlankDelay1 may be useful. For S3 Trio32/T rio64 cards, only InvertVCLk iS 
available. At the moment there are no default settings available for these chips in the video mode extension and thus this 
feature is disabled in xvidtune. It can be enabled by setting any of the optional S3 commands in the scree section of 
xF8é6Config, for example, using 


blank delay "" 0 


OPTIONS 


xvidtune accepts thestandard X Toolkit command-line options as well as the following: 


-prev Switch the xserver to the previous video mode. 
-next Switch the xserver to thenext video mode. 
-unlock Normally, xvidtune will disable the switching of video modes 


via hot keys whileit is running. If for some reason the program 
did not exit cleanly and they are still disabled, the program can 
be rerun with thisoption to reenable the mode switching key 
combinations. 


-saver suspendtime [offtime] Set the suspend and off screen saver inactivity time-outs. The 
values are in seconds. 
-query Display the monitor parameters and extended screen saver 
time-outs. 
SEE ALSO 
XF86Config(4/5) 
AUTHORS 


Kaleb S. Keithley (X Consortium), additions and modifications by Jon Tombs, D avid D awes, and Joe M oss 
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Xvminitoppm 
xvminitoppm— Convert an XV thumbnail picture to PPM 


SYNOPSIS 


xvminitoppm [xvmi ni pic] 


DESCRIPTION 


Reads an XV thumbnail picture (a miniature picture generated by the VisualSchnauzer browser) as input. Produces a 
portable pixmap as output. 


SEE ALSO 
ppm(5), xv(1) 
AUTHOR 
Copyright (c) 1993 by Ingo Wilken 
14 December 1993 
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xwd— D ump an image of an X window 
SYNOPSIS 
xwd [-debug] [-help] [-nobdrs] [-out file] [-xy] [-frame] [-add value] 
[-root j -id id j -name name ] [-icmap] [-screen] [-display display] 
DESCRIPTION 


xwd isan X Window Systen window dumping utility. xwa allows X users to store window images in a specially formatted 
dump file T his file can then be read by various other X utilities for redisplay, printing, editing, formatting, archiving, image 
processing, and so on. The target window is selected by clicking the pointer in the desired window. The keyboard bell is 
rung once at the beginning of the dump and twice when the dump is completed. 


OPTIONS 


-display display 


-help 
-nobdrs 


-out file 


“xy 


-add value 


-frame 


-root 


-id id 


-name name 


-icmap 


-screen 


This argument allows you to specify the server to connect to; 
see x(1), 

Print out the usage: command syntax summary. 

This argument specifies that the window dump should not 
include the pixels that compose the X window border. Thisis 
useful in situations in which you may wish to include the 
window contents in adocument as an illustration. 

This argument allows the user to explicitly specify the output 
fileon the command line The default is to output to standard 
out. 
This option applies to color displays only. It selects xv format 
dumping instead of the default z format. 

This option specifies a signed value to be added to every pixel. 
This option indicates that the window manager frame should 
beincluded when manually selecting a window. 

This option indicates that the root window should be selected 
for the window dump, without requiring the user to sdect a 
window with the pointe. 

This option indicates that the window with the specified 
resourcei d should be selected for the window dump, without 
requiring the user to select a window with the pointer. 

This option indicates that the window with the specified 
WM_NAME property should be selected for the window dump, 
without requiring the user to sdect a window with the pointer. 
Normally, the colormap of the chosen window is used to 
obtain RGB values. This option forces the first installed 
colormap of the screen to be used instead. 

This option indicates that the Get Image request used to obtain 
the image should be done on the root window, rather than 
directly on the specified window. In this way, you can obtain 
pieces of other windows that overlap the specified window, 
and moreimportantly, you can capture menus or other 

popups that are independent windows but that appear over the 
specified window. 
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ENVIRONMENT 
DISPLAY To get default host and display number 


FILES 


XWDFile.h X W indow dump file format definition file. 


SEE ALSO 
xwud(1), xpr(1), x(1) 


AUTHORS 


Tony D dla Fera(D igital Equipment Corporation, MIT Project Athena) and William F. W yatt (Smithsonian Astrophysical 
O bservatory) 
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xwdtopnm— Convert an X11 or X10 window dump file into a portable anymap 


SYNOPSIS 


xwdtopnm [xwdfile] 


DESCRIPTION 
Reads an X11 or X10 window dump file as input. Produces a portable anymap as output. T he type of the output file 
depends on the input file. If it’s black and white, a pbm file is written; if it's grayscale a pgm file else a ppm file. The program 
tells you which type it is writing. 
Using this program, you can convert anything on an X workstation’s scren into an anymap. J ust display whatever you're 
interested in, do an xwd, run it through xwdtopnm, and then use pnmcut to select the part you want. 


BUGS 

| haven't tested this tool with very many configurations, so there are probably bugs. Please let me know if you find any. 
SEE ALSO 

pnmtoxwd(1), pnm(5), xwd(1) 
AUTHOR 

Copyright (c) 1989, 1991 by] ef Poskanzer. 

11 January 1991 

xwininfo 

xwininfo— W indow information utility for X 
SYNOPSIS 

xwininfo [-help] [-id id] [-root] [-name name] [-int] [-children] [-tree] 


[-stats] [-bits] [-events] [-size] [-wm] [-shape] [-frame] [-all] [-english] 
[-metric] [-display display] 


DESCRIPTION 
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xwininfo is a utility for displaying information about windows. Various information is displayed depending on which options 


are selected. If no options are chosen, -stats is assumed. 


Theuser has the option of selecting the target window with the mouse (by clicking any mouse button in the desired 
window) or by specifying its window ia on the command line with the -id option. Or instead of specifying the window by 
its id numbey, the -name option may be used to specify which window is desired by name There is also a special -root 
option to quickly obtain information on the screen’s root window. 


OPTIONS 


-help 
-id id 


-name name 


-root 


-int 


-children 
-tree 


-stats 


-bits 


-events 


-size 


Print out the Usage: command syntax summary. 

This option allows the user to specify a target window id on 
the command line rather than using the mouse to select the 
target window. This is very useful in debugging X applications 
where the target window isnot mapped to the screen or where 
the use of the mouse might be impossible or interfere with the 
application. 

This option allows the user to specify that the window name is 
the target window on the command line rather than using the 
mouse to select the target window. 

This option specifies that X's root window is the target 
window. T his is useful in situations where the root window is 
completely obscured. 

This option specifies that all X window ias should be 
displayed as integer values. T he default is to display them as 
hexadecimal values. 

This option causes the root, parent, and children windows’ ids 
and names of the selected window to be displayed. 

This option is like -children but displays all children 
recursively. 
This option causes the display of various attributes pertaining 
to the location and appearance of the sdected window. 
Information displayed includes the location of the window, its 
width and haght, its deoth, border width, class, colormap id if 
any, map state, backing-store hint, and location of the corners. 
This option causes the display of various attributes pertaining 
to the selected window’s raw bits and how the selected window 
is to be stored. D isplayed information includes the selected 
window's bit gravity, window gravity, backing-store hint, 
backing-planes value, backing pixd, and whether or not the 
window has save-under set. 

This option causes the selected window’s event masks to be 
displayed. Both the event mask of events wanted by some 
client and the event mask of events not to propagate are 
displayed. 

This option causes the selected window's sizing hints to be 
displayed. Displayed information includes the following: for 
both the normal size hints and the zoom size hints, the user 
supplied location, if any; the program supplied location, if any; 
the user supplied size, if any; the program supplied size, if any; 
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-shape 
-frame 


-metric 
-english 
-all 


-display display 


EXAMPLE 


the minimum size if any; the maximum size, if any; the resize 
increments, if any; and the minimum and maximum aspect 
ratios, if any. 

This option causes the selected window's window manager 
hints to be displayed. Information displayed may include 
whether or not the application accepts input, what the 
window's icon window # and nameis, where the window’s 
icon should go, and what the window’s initial state should be. 
This option causes the selected window's window and border 
shape extents to be displayed. 

This option causes window manager frames to be considered 
whe manually selecting windows. 

This option causes all individual height, width, and x and y 
positions to be displayed in millimeters as well as number of 
pixds, based on what the server thinks the resolution is. 
Geometry specifications that are in +x+y form are not changed. 
This option causes all individual height, width, and x and y 
positions to be displayed in inches (and feet, yards, and miles if 
necessary) as well as number of pixels. -metric and -english 
may both be enabled at the same time 

This option is a quick way to ask for all information possible 


This option allows you to specify the server to connect to; see 
x(1). 


The following isa sample summary taken with no options specified: 


xwininfo: Window id: @x60000f "xterm" Absolute upper-left X: 2 

Absolute upper-left Y: 85 Relative upper-left X: @ Relative upper-left Y: 25 
Width: 579 Height: 316 Depth: 8 Visual Class: PseudoColor Border width: 0 
Class: InputOutput Colormap: 0x27 (installed) Bit Gravity State: 
NorthWestGravity Window Gravity State: NorthWestGravity Backing Store State: 
NotUseful Save Under State: no Map State: IsViewable Override Redirect State: 
no Corners: +2+85 -699+85 -699-623 +2-623 -geometry 80x24+0+58 


ENVIRONMENT 


DISPLAY 


SEE ALSO 
x(1), xprop(1) 


BUGS 


Using -stats -bits shows some redundant information. 


To get the default host and display number 


The -geometry string displayed must make assumptions about the window’s border width and the behavior of the application 
and the window manager. As aresult, the location given is not always correct. 


AUTHOR 


Mark Lillibridge (MIT Project Athena) 


X Verdon 11 Reease 6 
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xwud 
xwud— Image displayer for X 


SYNOPSIS 


xwud [-in file] [-noclick] [-geometry geom] [-display display] 
[-new] [-std <maptype>] [-raw] [-vis <vis-type-or-id>] [-help] [-rv] 
[-plane number] [-fg color] [-bg color] 


DESCRIPTION 


xwud is an X Window System image undumping utility. xwud allows X users to display in a window an image saved in a 
specially formatted dump file such as produced by xwa(1). 





OPTIONS 

-bg color If a bitmap image (or a single plane of an image) is displayed, 
this option can be used to specify the color to display for the 0 
bits in the image. 

-display display This option allows you to specify the server to connect to; see 
x(1). 

-fg color If a bitmap image (or a single plane of an image) is displayed, 
this option can be used to specify the color to display for the 1 
bits in the image. 

-geometry geom This option allows you to specify the size and position of the 


window. Typically, you will only want to specify the position, 
and let the size default to the actual size of the image. 


-help Print out a short description of the allowable options. 

-in file This option enables the user to explicitly specify the input file 
on the command line. If no input file is given, the standard 
input is assumed. 

-new This option forces creation of anew colormap for displaying 


the image. If the image characteristics happen to match those 
of the display, this can get the image on the screm faster, but 
at the cost of using anew colormap (which on most displays 

will cause other windows to go Technicolor). 

-noclick Clicking any button in the window will terminate the 
application, unless this option is specified. Termination can 
always be achieved by typing q, a, or Ctrl+C. 

-plane number You can select a single bit plane of the image to display with 

this option. Planes are numbered with zero being the least 

significant bit. T his option can be used to figure out which 
plane to pass to xpr(1) for printing. 

-raw This option forces the image to be displayed with whatever 
color values happen to currently exist on the screen. This 

option is mostly useful when undumping an image back onto 

the same screen that the image originally came from, while the 
original windows are still on the screen, and results in getting 
the image on the screen faster. 

“rv If a bitmap image (or a single plane of an image) is displayed, 
this option forces the foreground and background colors to be 
swapped. T his may be needed when displaying a bitmap image 
that has the color sense of pixd values a and 1 reversed from 
what they are on your display. 
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-std maptype This option causes the imageto be displayed using the 
specified standard colormap. T he property name is obtained 
by converting the type to uppercase, prepending res, and 
appending map. T ypical types are best, default, and gray. See 
xstd-cmap(1) for one way of creating standard colormaps. 

-vis vis-type-or-id This option allows you to specify a particular visual or visual 
class. T he default is to pick the “best” one A particular class 
can be specified: staticGray, GrayScale, StaticColor, 
PseudoColor, DirectColor, OF TrueColor. Or Match Can be 
specified, meaning use the same class as the source image. 
Alternatively, an exact visual id (specific to the server) can be 
specified, athe asa hexadecimal number (prefixed with ox) or 
as a decimal number. Finally, default can be specified, 
meaning to use the same class as the colormap of the root 
window. Caseis not significant in any of these strings. 


ENVIRONMENT 
DISPLAY To ge default display 


FILES 


XWDFile.h X Window dump file format definition file 


SEE ALSO 
xwd(1), xpr(1), xstdcmap(1), x(1) 


AUTHOR 
Bob Schafler (MIT X Consortium) 
X Version 11 Release 6 


yomtopom 


ybmtopbm— C onvert a Bennet Yee “face” file into a portable bitmap 


SYNOPSIS 


ybmtopbm [facefile] 


DESCRIPTION 


Reads a file acceptable to the face and xbm programs by Bennet Y ee (bsy+@cs.cmu. edu). W rites a portable bitmap as output. 


SEE ALSO 


pbmtoybm(1), pobm(5), face(1), face(5), xbm(1) 
AUTHOR 
Copyright (c) 1991 by Jamie Zawinski and J & Poskanzev. 
6 M arch 1990 
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ytalk 


ytalk— A multiuser chat program. 


SYNOPSIS 


ytalk [-x] username... 


DESCRIPTION 


ytalk (V3.0 Patch Level 1) isin essence a multiuser chat program. It works almost exactly like the UNIX talk program and 
even communicates with the same talk daemon(s), but yTa1k allows for multiple connections. 


The username field may be formatted in several different ways: 


name Some user on your machine 

name@host Some user on a different machine 

name#tty Some user on a particular terminal 

name#tty@host Some user on aparticular tty on a different machine 
name@host#tty Same as name#tty@host 


You can specify multiple usernames on the command line, for example 


ytalk george fred@hissun.edu marc@grumpy.cc 


The -x option disables the X11 interface (described below). 


For each user on the command line, yta1k will attempt to connect to the talk daemon on the specified user’s host and 
determine if that user has left an invitation for you to call. If not, yta1k leaves an invitation for him and tdls his talk daemon 
to send an announcement to his screen. There is not yet a dedicated yta1k daemon, but there will be Right now, ytalk is 
able to communicate with both existing versions of UNIX talk daanons. For any particular host, ytaik will attempt to 
communicate with a talk daemon the caller's host also supports. If the two hosts have no daanon in common, then UN IX 
talk will not function at all, but a connection is possible through (and only through) ytaik. 


After a connection has been established between two users, they can chat back and forth to thar hearts’ content. The 
connection is terminated when one of then hits Control-C or selects Q uit from the main menu. 


ytalk is perfectly compatible with UNIX talk and they can even converse with each other without any problems. H owever, 
many of the features of ytalk can only operate when you are connected to a user who is also using ytalk. For the rest of this 
document, it will be assumed that all connected users are using ytalk unless otherwise stated. 


If you specified more than one user on the ytalk command line, then ytalk will process and add each user to the conversa- 
tion as they respond to your invitation. As each new user enters the conversation, the screen is further subdivided into 
smaller and smaller windows, one for each connected user. Right now, the number of connected users is limited by the 
number of lines on your terminal (or window), for each connected user needs at least three lines. 


ytalk does implenent primitive support of the X11 Windowing System. If the environment variable prspLay is set, then 
ytalk attanpts to connect to that X server. Further details about the X11 interface (and how to turn it off) are given later in 
this section. 


As each new user is added to the conversation, ytalk will transmit information about that user to all other connected ytalk 
users so that their screens will also subdivide and incorporate the new user. If the new user is using UNIX talk, then 
information about him will NOT be transmitted, as his screen would be unable to accept multiple connections. | have given 
brief thought to allowing at least the output of UNIX talk users to be transmitted to all connected ytaik users, but | have not 
written any code to do so. N ote that even though UN IX talk cannot handle multiple connections, it is still possible for yta1k 
to handle multiple UNIX “talk” connections. For example, george (using yta1k) could communicate with fred and joe (both 
using UN IX talk), but fred and joe would be unaware of each other. The best way to understand the limitations that UNIX 
“talk” places on ytalk isto test various connections between the two and see how things work. 
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ESCAPE MENU 

Whenever you are using ytalk, you can hit the Escape key to bring up a menu that at this moment has these options: 
a Add a user 
d D elete a user 
) Options 
s Shel 
u User list 
w Output user to file 
q Quit 


By choosing option a, you are given the opportunity to type the name of any user you wish to include into the conversation. 
Again, YTALK will accept an invitation from that user if an invitation exists, or will leave an invitation and ring the given user. 


By choosing option a, you can sdect the name of a connection to terminate. 


By choosing option o, you can view and/or modify any of the ytalk options. (See the “O ptions” subsection for a list of ytaik 
options.) 


By choosing option s, you can invoke a shell in your ytaik window. All other users will see what happens in your shal. ytalk 
will automatically resize your window down to the size of the smallest window you are connected to, in order to ensure that 
all users always see the same thing. 





Theu option displays a list of connected and unconnected users, as well as their window sizes and what version of talk 
software they are running. 


By choosing option w, you can sdect any connected user and type the name of afile and all further output from that user 
will be dumped to the specified file. The file, if it exists, will be overwritten. If you choose w and the same user again, further 
output to the file will be terminated. 


Oh, one othe thing: when user A attenpts to ytalk to user B, but user B is already ytalking with user C, user A’s ytalk 
program will realize that user B is already using ytalk, and will communicate with user B’s ytalk program directly in order to 
initialize the conversation. U ser B will see anice windowed message such as 

Do you wish to talk with user A? 


and he will be prompted for a yes/no answe.. This, in my opinion, is much preferable to blitting the announcement message 
and messing up user B’s screen. 


RUNTIME OPTIONS 


W hen you select Options from the main menu, you are given the opportunity to edit the yta1k options. The current options 
are 


e Turn scrolling [off/on] 
7 Turn word-wrap [off/on] 
i Turn auto-import [off/on] 
f Turn auto-invite [off/on] 
r Turn auto-rering [off/on] 
a Turn asides [off/on] 


If scrolling is turned on, then auser’s window will scroll when he reaches the bottom, instead of wrapping back around to 
the top. 


If word-wrap is turned on, then any word that would overextend the right margin will be automatically moved to the nett line 
on your screen. 
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If auto-import is turned on, then ytaik will assume that you wish to talk to any users that connect to other ytaik users that 
are connected to you. T hat last sentence does make sense try again. ytalk will add these users to your session automatically, 
without asking you for verification. 


If auto-invite isturned on, then ytaik will automatically acceot any connection requested by another user and add the user 
to your session. You will not be asked for verification. 


If auto-rering isturned on, then ytalk will automatically rering any user who does not respond to your invitation within 30 
seconds. You will not be asked for verification. 





If asides isturned on (it may not be available), then keyboard input recaved while the input focus isin a specific user’s 
window will only be sent to that user. (See the “X11 Interface” subsection.) 


Any of these options can be set to your preference in your .ytalkrc file, as described in the next subsection. 


YTALK STARTUP FILE 


If your home directory contains afilenamed .ytalkrc, then ytaik will read this file while starting up. All ytalk runtime 
options, as well assome startup options, can be set in thisfile 


SETTING BOOLEAN OPTIONS 
Boolean options can be preset with the following syntax: 
turn option [off | on] 
where option iS one Of scrolling, word-wrap, auto-import, auto-invite, auto-rering, asides, Or x. Setting these options works 


just like described earlier in this section. T urning x on or off will enable or disable the X11 Interface For example, one could 
enable word-wrap with theline: 


turn word-wrap on 


SETTING READDRESS MODES 


The purpose of readdressing isto allow ytalk connections across point-to-point network gateways where the local machines 
know themselves by a different address (and typically hostname) than the renote machines. T he basic syntax of areaddress 
command is this: 


readdress from-address to-address domain 
The readdress statement simply makes a claim that the machine(s) in domain communicate with the machine(s) at fr om- 
address by sending a packet to to- address . Because most users have no use for this whatsoeve,, I'll describe it only briefly. 


THISISNOT ROUTING. For example, my machine at home is connected via PPP to the network at my office My 
machine at home thinks its Ethernet address is 192.188.253.1 and its hostname is “talisman.com”. The network at my office 
has the address 192.67. 141.0. When I’m connected via PPP, my home machine is placed into the office network as address 
192.67.141.9 with hostname “talisman. austin.eds.com”. 


ytalk needs to know that if it is running on domain 192.67. 141.0 and receives packets from 192. 188.253.1 that it should 
respond to 192.67.141.9, not 192.188.253.1. Right? Right. O Kay, okay, okay. | put thislineinto my .ytalkre on both ends: 


readdress talisman talisman.austin.eds.com 192.67.141.0 
On my home end, this translates to 
readdress 192.188.253.1 192.67.141.9 192.67.141.0 


which tells my home machine to advertise itself as 192.67.141.9 instead of 192.188.253.1 when ytalking to machines on the 
network 192.67.141.0. On the office end, the readdress command translates to 


readdress 192.67.141.9 192.67.141.9 192.67.141.0 
which the office machines basically ignore 
Enough. For more information on how to use this, consult the source code or send mea letter. :-) 
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X11 INTERFACE 
If the prspLay environment variable is defined when ytaik starts up, then ytaik will attempt to communicate with that X 
server. A window will be created for you and each user you are connected to. The X11 Interface can be disabled either by 
specifying -x on the command line or by putting this lineinto your .ytalkre file 
turn X off 
A window is created for each individual user in the conversation. If the input focus isin the main window (the one with 
ytalk in the title bar) then anything typed will be sent to all connected users. If the input focus isin one of the user's 


windows, then anything typed will be sent as an aside to only that user. If the aside option is turned off, then ytalk will beep 
and not accept anything typed when the input focus is not in the main window. 


ytalk consults the X11 Resource D atabase for these user-definable configuration options: 








ytalk.display: X server to connect to, defaulting to the prspLay environment variable. 
ytalk.reverse: Reverse black/white pixels. 
ytalk.font: Font to use, defaulting to 9x15. 
ytalk.geometry: Window size, defaulting to 8ex24. 
FUTURE WORK 


W ork is being done on the following ideas: 


m Private conversations that do not ge interrupted or transmitted to all ytalk connections 
m A dedicated ytalk daemon 


FILES 
/usr/local/etc/ytalkre Systemwide defaults file 
$HOME/.ytalkre User's local configuration file. T his file overrides options set in 
the system ytalkrc file 
AUTHOR 
Britt Y enne (yenne@austin. eds.com) 
CONTRIBUTORS 


Special thanks to Carl Edman for numerous code patches, beta testing, and comments. | think this guy spends as much time 
On ytalk as! do. Special thanks to T obiasH ahn and Geoff W. for beta testing and suggestions. T hanks to Sitaram 
Ramaswamy for the original yta1k man page T hanks to M agnus H ammerin for Solaris 2.* support. Thanks to J onas 
Yngvesson for aside messages in X. Thanks to Andreas Stolcke for fixing the X resource database calls. Thanks to John 
Vanderpool, Shih-C hen H uang, Andrew M yers, D uncan Sinclair, Evan M cLean, and Larry Schwimmer for comments and 
ideas. The README file shipped with yta1k gives detailed attributions. 


BUGS 


If you have any ideas, comments, or questions, |’d be happy to hear from you at ytalk@austin.eds.com. 
24 June1993 


yuvplittoppm 


yuvplittoppm— C onvet ay-, au-, and av- fileinto aportable pixmap. 


SYNOPSIS 


yuvsplittoppm basename width height [-ccir601] 


zcmp, Zdiff Bl 


DESCRIPTION 


Reads three files, containing the YUV components, as input. T hese files are basename.Y, basename.U and basename.v. Produces 
a portable pixmap on stdout. 


SincetheYUV files are raw files, the dimensions width and height must be specified on the command line 


OPTIONS 
-ccir6dt Assumes that the YUV triplets are scaled into the smaller range 
of theCCIR 601 (M PEG) standard. O therwise the] FIF 
(JPEG) standard is assumed. 
SEE ALSO 
ppmtoyuvsplit(1), yuvtoppm(1), ppm(5) 
AUTHOR 


M arcel W ijkstra (<wijkstra@fwi.uva.n1>), based ON ppmtoyuvsplit 
26 August 1993 


yuvtoppm 


yuvtoppm— Convert Abekas YU V bytes into a portable pixmap 
SYNOPSIS 


yuvtoppm width height [i magedata ] 


DESCRIPTION 
Reads raw Abekas YUV bytes as input. Produces a portable pixmap as output. The input file is just YUV bytes. You have to 
specify the width and height on the command line since the program obviously can’t get them from the file T hemaxval is 
assumed to be 255. 

SEE ALSO 
ppmtoyuv(1), ppm(5) 

AUTHOR 


M arc Boucher (<marc@PostImage.com>)), based on Example Conversion Program, A60/A64 Digital Video Interface M anual, 
page 69. Copyright (c) 1991 by DHD Postl mage, Inc. Copyright (c) 1987 by Abekas Video Systems, Inc. 


25 March 1991 


zcmp, 2diff 


zemp, zdiff— C ompare compressed files 


SYNOPSIS 


zcmp [ cmp_options ] file1 [ file2 ] 
zdiff [diff_options ] file1 [ file2 ] 
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DESCRIPTION 
Zemp and zdiff are used to invoke the cmp or the diff program on compressed files. All options specified are passed directly to 
cmp Or diff. If only one file is specified, then the files compared are filet and an uncompressed file1.gz. If two files are 
specified, then they are uncompressed if necessary and fed to cmp or diff. T he exit status from cmp or diff is preserved. 


SEE ALSO 
emp(1), dift(1), zmore(1), zgrep(1), znew(1), zforce(1), gzip(1), gzexe(1) 
BUGS 
M essages from the cmp or diff programs refer to temporary filenames instead of those specified. 
zeisstopnm 
zeisstopnm— Convert a Zeiss confocal file into a portable anymap 
SYNOPSIS 
zeisstopnm [-pgm j -ppm][zeissfile] 
DESCRIPTION 


Reads a Zdiss confocal file as input. Produces a portable anymap as output. T he type of the output file depends on the input 
file— if it’s grayscale, a pgm file will be produced; otherwise, it will be a ppm file The program tells you which type it is 
writing. 


OPTIONS 


-pgm Force the output to bea pgm file 
-ppm Force the output to be a ppm file 


SEE ALSO 
pnm(5) 
AUTHOR 
Copyright (c) 1993 by Oliver T repte. 
15 June1993 


zforce 


zforce— Forcea .gz extension on all gzip files 


SYNOPSIS 


zforce [ name ... ] 


DESCRIPTION 


zforce forcesa .gz extension on all gzip files so that gzip will not compressthem twice. T his can be useful for files with 
names truncated after a file transfer. On systems with a 14-character limitation on filenames, the original name is truncated 
to make room for the .gz suffix. For example, 12345678901234 is renamed to 12345678901 .gz. A filename such as foo. tgz is left 
intact. 
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SEE ALSO 


gzip(1), znew(1), zmore(1), zgrep(1), zdift(1), gzexe(1) 


zgrep 


zgrep— Search possibly compressed files for a regular expression 


SYNOPSIS 


zgrep [ grep_options ] [-e] pattern filename... 


DESCRIPTION 


zgrep iS used to invoke the grep on compressed or gziped files. All options specified are passed directly to grep. If no file is 
specified, then the standard input is decompressed if necessary and fed to grep. O therwise, the given files are uncompressed if 
necessary and fed to grep. 


If zgrep isinvoked as zegrep Or zfgrep, then egrep Or fgrep is used instead of grep. If the REP environment variable is set, 
zgrep uses it as the grep program to beinvoked. For example, 


for sh: GREP=fgrep zgrep string files for csh: (setenv GREP fgrep; zgrep string files) 


AUTHOR 


Charles Levert (charles@comm. polymt1.ca) 


SEE ALSO 


grep(1), egrep(1), fgrep(1), zditt(1), zmore(1), znew(1), zforce(1), gzip(1), gzexe(1) 


zmore 


zmore— File perusal filter for crt viewing of compressed text 


SYNOPSIS 


zmore [ name ... ] 


DESCRIPTION 


zmore iS afilter that allows examination of compressed or plain text files one screenful at a time on a soft-copy taminal. zmore 
works on files compressed with compress, pack, OF gzip, and also on uncompressed files. If a file does not exist, zmore looks for 
a file of the same name with the addition of a.gz, .z, or .z suffix. 


zmore normally pauses after each screenful, printing -more- at the bottom of the screen. If the user then types a carriage 
return, one more line is displayed. If the user hits a space, another screenful is displayed. O ther possibilities are enumerated 
later. 


zmore looksin the file /etc/termcap to determine terminal characteristics, and to determinethe default window size Ona 
terminal capable of displaying 24 lines, the default window size is 22 lines. To use a pager other than the default more, set 
environment variable pacer to the name of the desired program, such as less. 


O ther sequences that may be typed when zmore pauses, and their effects, are as follows (i isan optional integer argument, 
defaulting to 1) : 


i <space> Display i more lines, (or another screenful if no argument is 
given). 

D Display 11 more lines (a “scroll”). If i is given, then the scroll 
size is set to i. 


d Same as “p (control-D) 
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is 
if 
q ora 
eOrgq 


i /expr 


!command 


:q OF :Q 


Same as typing a space except that i, if present, becomes the 
new window size N ote that the window size reverts back to 
the default at the end of the current file. 

Skipi lines and print a screenful of lines. 

Skipi screenfuls and print a screenful of lines. 

Quit reading the current file; go on to the next (if any). 

When the prompt -More-(Next file: file) isprinted, this 
command causes zmore to exit. 

When the prompt -More-(Next file: file) isprinted, this 
command causes zmore to skip the next file and continue 
Display the current line number. 

Search for thei th occurrence of the regular expression expr. If 
the pattern is not found, zmore goes on to the nett file (if any). 
Otherwise, ascreenful is displayed, starting two lines before 
the place where the expression was found. T he user’s erase and 
kill characters may be used to edit the regular expression. 
Erasing back past the first column cancels the search 
command. 

Search for thei th occurrence of the last regular expression 
entered. 

Invokea shell with command. Thecharacter ! in command iS 
replaced with the previous shell command. T he sequence \! is 
replaced by !. 

Quit reading the current file, go on to the next (if any) (same 
aSq ora). 

(dot) Repeat the previous command. 


The commands take effect immediately; that is, it is not necessary to type a carriage return. Up to the time when the 
command character itself is given, the user may hit the line kill character to cancd thenumerical argument being formed. In 
addition, the user may hit the erase character to redisplay the -more- message. 


At any time when output is being sent to the teminal, the user can hit the quit key (normally C ontrol-n). zmore will stop 
sending output, and will display the usual -more- prompt. T he user may then enter one of the preceding commands in the 
normal manne. Unfortunately, some output is lost when this is done because any characters waiting in the terminal’s output 


queue are flushed when the quit signal occurs. 


The terminal is set to noecho mode by this program so that the output can be continuous. W hat you type will thus not show 


on your terminal, except for the / and : commands. 


If the standard output is not a teletype, then zmore acts just like zcat, except that a header is printed before each file 


FILES 


/etc/termcap Terminal database 


SEE ALSO 


more(1), gzip(1), zdift(1), zgrep(1), znew(1), zforce(1), gzexe(1) 


znew 


znew— Recompress Z files to GZ files 


SYNOPSIS 


znew [ -ftv9PK] [ name.Z ... ] 


znew 


DESCRIPTION 
znew recompresses files from Z (compress) format to GZ (gzip) format. If you want to recompress a file already in gzip 
format, rename the file to force a .z extension, then apply znew. 
OPTIONS 
-f Force recompression from Z to GZ format even if aGZ file 
already exists. 
-t Test the new files before ddeting originals. 
“V Verbose. Display the name and percentage reduction for each 
file compressed. 
-9 Use the slowest compression method (optimal compression). 
-P Use pipes for the conversion to reduce disk space usage. 
-K Keep aZ file when it issmaller than the GZ file. 
SEE ALSO 
gzip(1), zmore(1), zditt(1), zgrep(1), zforce(1), gzexe(1), compress(1) 
BUGS 


znew does not maintain the timestamp with the -p option if cpmod(1) is not available and touch(1) does not support the -r 
option. 
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intro 


intro— Introduction to system calls 


DESCRIPTION 


This chapter describes the Linux system calls. 


CALLING DIRECTLY 


In most cases, it is unnecessary to invoke a system call directly, but there are times when thestandard C library does not 
implement anice function call for you. 


SYNOPSIS 
#include <linux/unistd.h> 
A _syscall macro 
Desired system call 


SETUP 


Theimportant thing to know about a system call is its prototype. You need to know how many arguments, their types, and 
the function return type Six macros make the actual call into the systen easier. They have the form 


syscallX(type,name ,typel,argl,type2 ,arg2,...) 


where 

x 0-5, which are the number of arguments taken by the system call 
type The return type of the system call 

name Thename of the system call 

typen TheN th argument’s type 

argN The name of the N th argument 


T hese macros create a function called name with the arguments you specify. O nce you include _syscall() in your source file, 
you call the systen call by name. 


EXAMPLE 


{ 
struct sysinfo s_info; 
int error; 


error = sysinfo(&s_info) ; 
printf("code error = %d\n", error); 
printf ("Uptime = %ds\nLoad: 1 min %d / 5 min %d / 15 min %d\n" 
"RAM: total %d / free %d / shared %d\n" 
"Memory in buffers = %d\nSwap: total %d / free %d\n" 
"Number of processes = %d\n", 
s_info.uptime, s_info.loads[Q], 
s_info.loads[1], s_info.loads[2], 
s_info.totalram, s_info.freeram, 
s_info.sharedram, s_info.bufferram, 
s_info.totalswap, s_info.freeswap, 
s_info.procs) ; 
return(0); 


exit 739 


SAMPLE OUTPUT 


code error = 0 

uptime = 502034s 

Load: 1 min 13376 / 5 min 5504 / 15 min 1152 

RAM: total 15343616 / free 827392 / shared 8237056 
Memory in buffers = 5066752 

Swap: total 27881472 / free 24698880 

Number of processes = 40 


NOTES 
The_syscal1() macros do not produce a prototype. You might have to create one, especially for C ++ users. 


System calls are not required to return only positive or negative error codes. You nead to read the source to be sure how it 
will return errors. Usually, it is the negative of a standard error code, for example, -EPpeRM. The _syscal1() macros will return 
the result r of the system call whenr is nonnegative but will return -1 and set the variable errno to -r whenr is negative. 


Some system calls, such aS mmap, require more than five arguments. T hese are handled by pushing the arguments on the stack 
and passing a pointer to the block of arguments. 


When defining a system call, the argument types must be passed by value or by pointer (for aggregates such as structs). 
FILES 


/usr/include/linux/unistd.h 


AUTHORS 


Look at the header of the manual page for the author(s) and copyright conditions. N ote that these can be different from page 
to page. 


Linux 1.2.13, 22 May 1996 


exit 
exit— T eminate the current process 


SYNOPSIS 


#include <unistd.h> 
void exit(int status); 


DESCRIPTION 


exit terminates the calling processimmediatdy. Any open file descriptors belonging to the process are closed; any children of 
the process are inherited by process 1, init, and the process's parent is sent a SIGCHLD signal. 


status isreturned to the parent process as the process's exit status and can be collected using one of the wait family of calls. 


RETURN VALUE 


exit Neve returns. 


CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


NOTES 


exit does not call any functions registered with the AN SI C atexit function and does not flush standard |/O buffers. To do 
these things, use exit(3). 
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SEE ALSO 
fork(2), execve(2), waitpid(2), wait4(2), kil1(2), wait(3), exit(3) 
Linux, 21 July 1993 


accept 


accept— Accept a connection on a socket 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/socket.h> 
int accept(int s, struct sockaddr *addr ,int*addrlen); 


DESCRIPTION 


Thearguments isasocket that has been created with socket(2), bound to an address with bind(2), and is listening for 
connections after a listen(2). T he accept function extracts the first connection request on the queue of pending connec- 
tions, creates a new socket with the same propaties of s, and allocates a new file descriptor for the socket. If no pending 
connections are present on the queue and the socket is not marked as nonblocking, accept blocks the caller until a connec- 
tion is present. If the socket is marked nonblocking and no pending connections are present on the queue, accept returns an 
error as described below. T he accepted socket may not be used to accept more connections. T he original sockets remains 
open. 


The argument addr isa result parameter that is filled in with the address of the connecting entity, as known to the communi- 
cations layer. The exact format of theaddr parameter is determined by the domain in which the communication is occurring. 
Theaddri en isa value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will 
contain the actual length (in bytes) of the address returned. T his call is used with connection-based socket types, currently 
with sock_STREAM. 


It is possible to select (2) a socket for the purposes of doing an accept by selecting it for read. 


For certain protocols that require an explicit confirmation, such as 1so and DATAKIT, accept Can be thought of asmerdy 
dequeuing the next connection request and not implying confirmation. Confirmation can be implied by anormal read or 
write on the new file descriptor, and rejection can be implied by closing the new socked. 


Onecan obtain user connection request data without confirming the connection by issuing a recvmsg(2) call with amsg 
iovlen of @ and anonzero msg controllen, or by issuing a getsockopt (2) request. Similarly, one can provide user connection 
rejection information by issuing a sendmsg(2) Call providing only the control information, or by calling setsockopt (2). 





RETURN VALUES 

The call returns -1 on error. If it succeeds, it returns a nonnegative integer that is a descriptor for the accepted socket. 
ERRORS 

EBADF The descriptor is invalid. 

ENOTSOCK The descriptor references a file not a socket. 

EOPNOTSUPP The referenced socket is not of type sock_STREAM. 

EFAULT The addr parameter isnot in a writable part of the user address space. 

EWOULDBLOCK The socket is marked nonblocking and no connections are present to be accepted. 
HISTORY 


The accept function appeared in BSD 4.2. 
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SEE ALSO 


bind(2), connect(2), listen(2), select(2), socket (2) 
BSD Man Page 24 July 1993 


access 


access— Checks user's permissions for a file 


SYNOPSIS 


#include <unistd.h> 
int access(const char *pathname ,intmode); 


DESCRIPTION 


access checks whether the process would be allowed to read, write, or test for existence of the file (or other file system object) 
whose name ispathname. If pathname isasymbolic link, permissions of the file referred by this symbolic link are tested. 


mode iS a mask consisting of one or more of R_OK, W_OK, X_OK, and F_OK. 


R_OK, W_OK, and x_ok request checking whether the file exists and has read, write, and execute permissions, respectively. F_ok 
just requests checking for the existence of the file. 

The tests depend on the permissions of the directories occurring in the path to the file, as given in pathname, and on the 
permissions of directories and files referred by symbolic links encountered on the way. 

The check is done with the process's real UID and GID, rather than with the effective|D s as is done when actually 
attempting an operation. Thisis to allow se-UID programs to easily determine the invoking user’s authority. 

Only access bits are checked, not the file type or contents. Therefore, if a directory is found to be “writable,” it probably 


means that files can be created in the directory, and not that the directory can be written asa file Similarly, aD OS filemay 
be found to be “executable,” but the execve(2) call will still fail. 


RETURN VALUE 


On success (all requested permissions granted), @ is returned. On error (at least 1 bit in mode asked for a permission that is 
denied, or some other error occurred), -1 is returned and errno is set appropriately. 


ERRORS 
EACCES The requested access would be denied, either to the file itself or one of thedirectories in 
pathname. 
EFAULT pathname points outside your accessible address space. 
EINVAL mode was incorrectly specified. 
ENAMETOOLONG pathname iStoo long. 
ENOENT A directory component in pathname would have bee accessible but does not exist or was a 
dangling symbolic link. 
ENOTDIR A component used as a directory in pathname isnot, in fact, a directory. 
ENOMEM Insufficient kernel memory was available. 
ELOOP pathname Contains a reference to a circular symbolic link, that is, a symbolic link containing 
a reference to itself. 
RESTRICTIONS 


access returns an error if any of the access types in the requested call fails, even if other types might be successful. access may 
not work correctly on N FS file systems with UID mapping enabled because UID mapping is done on the server and hidden 
from the client, which checks permissions. 
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CONFORMS T0 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 


stat(2), open(2), chmod(2), chown(2), setuid(2), setgid(2) 
Linux 1.2.13, 17 M arch 1996 


acct 
acct— Switches process accounting on or off 


SYNOPSIS 


#include <unistd.h> 
int acct(const char *filename); 


DESCRIPTION 


Warning: Since this function is not implenented as of Linux 0.99.11, it will always return -1 and set errno to Enosvs. If 
acctkit isinstalled, the function performs as advertised. 


W hen called with the name of an existing file as argument, accounting is turned on and records for each terminating process 
are appended to filename as it terminates. An argument of NULL causes accounting to beturned off. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned and errno isse@t appropriately. 


NOTES 


No accounting is produced for programs running when acrash occurs. In particular, nonterminating processes are never 
accounted for. 


SEE ALSO 
acct(5) 
Linux 0.99.11, 10 August 1993 


adj timex 
adjtimex— T unes kernel clock 


SYNOPSIS 


#include <sys/timex.h> 
int adjtimex(struct timex *buf ); 


DESCRIPTION 


Linux uses D avid M ill’s clock adjustment algorithm. adjtimex reads and optionally sets adjustment parameters for this 
algorithm. 


adjtimex takes a pointer to ati mex structure, updates kernd parameters from field values, and returns the same structure with 
current kernel values. T his structure is declared as follows: 


adjtimex 143 


struct timex 





{ 
int mode; /* mode selector */ 
ong offset; /* time offset (usec) */ 
ong frequency; /* frequency offset (scaled ppm) */ 
ong maxerror; /* maximum error (usec) */ 
ong esterror; /* estimated error (usec) */ 
int status; /* clock command/status */ 
ong time_constant; /* pll time constant */ 
ong precision; /* clock precision (usec) (read only) */ 
ong tolerance; /* clock frequency tolerance (ppm) 
(read only) */ 
struct timeval time; /* (read only) */ 
ong tick; /* usecs between clock ticks */ 
hs 


Themode field determines which parameters, if any, to set. It may contain a bitwise or combination of zero or more of the 
following bits: 


#define ADJ_OFFSET 0x0001 /* time offset */ 
#define ADJ FREQUENCY @x0002 /* frequency offset */ 
#define ADJ_MAXERROR 0x0004 /* maximum time error */ 
#define ADJ_ESTERROR 0x0008 /* estimated time error */ 
#define ADJ_STATUS 0x0010 /* clock status */ 
#define ADJ_TIMECONST 0x0020 /* pll time constant */ 
#define ADJ_TICK 0x4000 /* tick value */ 


#define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime */ 


Ordinary users are restricted to aa value for mode. O nly the superuser may set any parameters. 


RETURN VALUE 
On Success, adjtimex returns the value of buf. status: 


#define TIME OK @ /* clock synchronized */ 
#define TIME INS 1 /* insert leap second */ 
#define TIME DEL 2 /* delete leap second */ 
#define TIME OOP 3 /* leap second in progress */ 
#define TIME BAD 4 /* clock not synchronized */ 


On failure, adjtimex returns -1 and sets errno. 


ERRORS 

EFAULT buf doesnot point to writable memory. 

EPERM buf. mode isnonzero and the user is not superuser. 

EINVAL An attempt is made to set buf. offset to a value outside the range -131071 to +131071, or 
to set buf. status to a value other than those listed above or to set buf. tick to avalue 
outside the range 900000/H Z to 1100000/H Z,where HZ is the system timer interrupt 
frequency. 

SEE ALSO 
settimeofday(2) 


Linux 1.2.4, 15 April 1995 
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alarm 


alarm— Sets an alarm clock for delivery of a signal 


SYNOPSIS 


#include <unistd.h> 
unsigned int alarm(unsigned int seconds); 


DESCRIPTION 


alarm arranges for a SIGALRM signal to be ddivered to the processin seconds seconds. 
If seconds iS@, NO NeW alarm is scheduled. 
In any event, any previously set alarm is canceled. 


RETURN VALUE 
alarm returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, or 0 if there 
was no previously scheduled alarm. 


NOTES 


alarm and setitimer share the same time; calls to one will interfere with use of the other. 
Scheduling delays can, as ever, cause the execution of the process to be delayed by an arbitrary amount of time 


CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 


setitimer(2), signal(2), sigaction(2), gettimeofday(2), select(2), pause(2), sleep(3) 
Linux, 21 July 1993 


bdflush 


bdflush— Starts, flushes, or tunes the buffer-dirty-flush daemon 


SYNOPSIS 


int bdflush(int func, long *address); 
int bdflush(int func, long data); 


DESCRIPTION 

bdflush starts, flushes, or tunes the buffer-dirty-flush daemon. O nly the superuser may call bdflush. 

If func is negative or 0 and no daemon has bem started, bdflush enters the daemon code and never returns. 
If func iS1, some dirty buffers are written to disk. 


If func iS2 or more and iseven (low bit is 0), address isthe address of along word, and the tuning parameter numbered 
func-2)/2 isreturned to the caller in that address. 


If func iS3 or more and isodd (low bit is 1), data isalong word and the kernd sets tuning parameter numbered (f unc -3) /2 
to that value. 


The set of parameters, ther values, and their legal ranges are defined in the kernd source filefs/buffer.c. 


al 
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RETURN VALUE 


If func is negative or o and the daemon successfully starts, bdflush never returns. O therwise, the return value iso on success 
and -1 on failure, with errno set to indicate the error. 


ERRORS 
EPERM Caller is not superuser. 
EFAULT address points outside your accessible address space. 
EBUSY An attempt was madeto enter the daenon code after another process has already been 
entered. 
EINVAL An attempt was madeto read or write an invalid parameter number, or to write an invalid 
value to a parameter. 
SEE ALSO 


fsync(2), sync(2), update(8), sync(8) 
Linux 1.2.4, 15 April 1995 


bind 
bind— Bindsa name to asockét 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/socket.h> 
int bind(int sockfd, struct sockaddr *my_addr ,intaddrlen); 


DESCRIPTION 


bind gives the socket, sockfd, thelocal address my addr. my_addr iSaddrien bytes long. Traditionally, thisiscalled assigning a 
nameto a socket. (When a socket is created with socket(2), it exists in anamespace— an address family— but has no name 
assigned.) 


NOTES 


Binding anamein the UNIX domain creates a socket in the file system that must be deleted by the calle— using unlink(2) 
— when it isno longer needed. 


The rules used in namebinding vary between communication domains. C onsult the manual entries in section 4 for detailed 
information. 


RETURN VALUE 
On success, a isreturned. On error, -1 iS returned, and errno is set appropriately. 
ERRORS 
EBADF sockfd isnot a valid descriptor. 
EINVAL The socket is already bound to an address. T his may changein the future. See linux/unix/ 
sock.c for details, 
EACCES The address is protected and the user is not the superuser. 


The following errors are specific to UNIX domain (aF_unrx) sockets: 

EINVAL addr | en was wrong, or the socket was not in the aF_unrx family. 
EROFS The socket inode would reside on a read-only file systen. 

EFAULT my_addr points outside your accessible address space. 


746 Part II: System Calls 


ENAMETOOLONG my_addr iS too long. 

ENOENT The file does not exist. 

ENOMEM Insufficient kernel memory was available. 

ENOTDIR A component of the path prefix is not a directory. 

EACCES Search permission is denied on acomponent of the path prefix. 

ELOOP my_addr Contains acircular reference (that is, viaa symbolic link). 
HISTORY 

The bind function call appeared in BSD 4.2. 
SEE ALSO 


accept(2), connect(2), listen(2), socket(2), getsockname(2) 
Linux 0.99.11, 23 July 1993 


ork, sork 


brk, sork— Change data segment size 


SYNOPSIS 


#include <unistd.h> 
int brk(void *end_data_segment ); 
void *sbrk(ptrdiff tincrement ); 


DESCRIPTION 
brk sets the end of the data segment to the value specified by end_data_segment. 
end_data_segment must be greater than the end of the text segment and it must be 16K B before the end of the stack. 
sbrk increments the program's data space by increment bytes. sbrk isn’t a system call; itis just aC library wrapper. 


RETURN VALUE 


On success, rk returns @, and sbrk returns a pointer to the start of the new area. On aor, -1 iSreturned and errno isset to 
ENOMEM. 


CONFORMS TO 


BSD 4.3 


brk and sbrk are not defined in theC standard and are deliberately excluded from the PO SIX.1 standard (see paragraphs 
B.1.1.1.3 and B.8.3.3). 


SEE ALSO 
execve(2), getrlimit(2), malloc(3), end(3) 
Linux 0.99.11, 21 July 1993 


cacheflush 


cacheflush— Flushes contents of the instruction and/or data cache 


SYNOPSIS 
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#include <asm/cachectl.h> 
int cacheflush(char *addr ,intnbytes ,intcache); 


DESCRIPTION 


cacheflush flushes contents of indicated cache{s) for user addresses in the range addr to (addr+nbytes-1). T he cache may be 
one of the following: 


ICACHE Flush the instruction cache. 

DCACHE W rite back to memory and invalidate the affected valid cache lines. 

BCACHE Same as (ICACHE | DCACHE). 
RETURN VALUE 

cacheflush returns @ on successor -1 on error. If errors are detected, errno will indicate the error. 
ERRORS 

EINVAL The cache parameter is not one of ICACHE, DCACHE, OF BCACHE. 

EFAULT Someor all of the address range addr to (addr+nbytes-1) isnot accessible. 
BUGS 

The current implementation ignores the addr and nbytes parameters. Therefore, the whole cache is always flushed. 
NOTE 

This system call is only available on M IPS-based systems. 
SEE ALSO 

cachect1(2) 


Linux, 27 June95 


chdir, fchdir 


chdir, fchdir— Changes the working directory 


SYNOPSIS 


#include <unistd.h> 
int chdir(const char *path); 
int fchdir(int fd); 


DESCRIPTION 
chdir changes the current directory to that specified in path. 
fchdir isidentical to chdir, only the directory is given asan open file descriptor. 


RETURN VALUE 
On success, a isreturned. On error, -1 iS returned, and errno is set appropriately. 

ERRORS 
Depending on the file system, other errors can be returned. The more general errors are listed here: 
EPERM The process does not have execute permission on the directory. 
EFAULT path points outside your accessible address space. 


ENAMETOOLONG path iS too long. 
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EBADF 
ENOENT 
ENOMEM 
ENOTDIR 
EACCES 
ELOOP 


SEE ALSO 


getcwd(3), chroot(2) 


chmod, fchmod 


fd isnot a valid file descriptor. 

The file does not exist. 

Insufficient kernel memory was available. 

A component of the path prefix is not a directory. 

Search permission is denied on acomponent of the path prefix. 
path contains a circular reference (that is, via a symbolic link) 


Linux 1.2.4, 15 April 1995 


chmod, fchmod— C hanges permissions of a file 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/stat.h> 


int chmod(const char *path,modetmode); 
int fchmod(int fildes ,modetmode ); 


DESCRIPTION 


Themode of the file given by path or referenced by filedes is changed. 


M odes are specified by oring the following: 


$_ISUID 
$_ISGID 
$_ISVTX 
S$ _IRUSR (S_IREAD) 
S_IwusR (S_IWRITE) 
$_IXUSR (S_IEXEC) 
S_IRGRP 
$_IWGRP 
$_IXGRP 
$_IROTH 
$_IWOTH 
$_IXOTH 


RETURN VALUE 


04000 Se user ID on execution 

02000 Se group ID on execution 

01000 Sticky bit 

00400 Read by owner 

00200 Write by owner 

00100 Execute/search by owner 

00040 Read by group 

00020 Write by group 

00010 Execute/search by group 

00004 Read by others 

00002 Write by others 

00001 Execute/search by others 

TheeffectiveUID of the process must be 0 or must match the owner of the file. 
The effectiveU ID or GID must be appropriate for setting execution bits. 


Depending on thefile systen, set user 1D and set group ID execution bits may be turned 
off if a file is written. On some file systems, only the superuser can set the sticky bit, which 
may have a special meaning (that is, for directories, a file can only be deleted by the owner 
or the superuser). 





On success, 0 is returned. On error, -1 isreturned and errno isse@t appropriately. 
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ERRORS 
Depending on the file system, other errors can be returned. The more general errors for chmod are listed here 
EPERM The effectiveU ID doesnot match the owner of the file and is not 0. 
EROFS The named file resides on a read-only file system. 
EFAULT path points outside your accessible address space. 
ENAMETOOLONG path iS too long. 
ENOENT The file does not exist. 
ENOMEM Insufficient kernel memory was available. 
ENOTDIR A component of the path prefix is not a directory. 
EACCES Search permission is denied on acomponent of the path prefix. 
ELOOP path contains a circular reference (that is, via a symbolic link) 


The general errors for fchmod are listed here: 


EBADF The descriptor is not value. 
ENOENT See above 
EPERM See above 
EROFS See above 
SEE ALSO 


open(2), chown(2), stat(2) 
Linux 0.99.11, 21 July 1993 


chown, fchown 


chown, fchown— C hanges ownership of a file 


SYNOPSIS 


#include <sys/types.h> 
#include <unistd.h> 

int chown(const char *path, uid t owner, gid t group); 
int fchown(int fd, uid t owner, gid_t group); 


DESCRIPTION 


The owner of thefile specified by path or byfd is changed. Only the superuser may change the owner of a file The owner of 
a file may change the group of thefile to any group of which that owner isa member. T he superuser may change the group 
arbitrarily. 





If the owner Of group iS Specified as -1, that!D isnot changed. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isse&t appropriately. 
ERRORS 
Depending on the file systen, other errors can be returned. The more general errors for chown are listed here 
EPERM The effective UID doesnot match the owner of the file, and is not 0; or theowner Or group 
were specified incorrectly. 
EROFS The named file resides on a read-only file system. 


EFAULT path points outside your accessible address space. 
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ENAMETOOLONG path iS too long. 

ENOENT The file does not exist. 

ENOMEM Insufficient kernel memory was available. 

ENOTDIR A component of the path prefix is not a directory. 

EACCES Search permission is denied on acomponent of the path prefix. 
ELOOP path contains a circular reference (that is, via a symbolic link). 


The general errors for fchown are listed here: 


EBADF The descriptor is not value. 

ENOENT See above 

EPERM See above 

EROFS See above 
NOTES 

chown does not follow symbolic links. The prototype for fchown is only available if use Bsp is defined. 
SEE ALSO 


chmod(2), flock(2) 
Linux 0.99.11, 21 July 1993 


chroot 


chroot— Changes root directory 


SYNOPSIS 


#include <unistd.h> 
int chroot(const char *path); 


DESCRIPTION 


chroot Changes the root directory to that specified in path. This directory will be used for pathnames beginning with /. The 
root directory is inherited by all children of the current process. 


Only the superuser may change the root directory. 
N ote that this call does not change the current working directory, so that . can be outside the tree rooted at /. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isse& appropriately. 
ERRORS 
Depending on the file system, other errors can be returned. The more general errors are listed here: 
EPERM The effective UID doesnot match the owner of the file, and is not 0; or theowner Or group 
were specified incorrectly. 
EROFS The named file resides on a read-only file system. 
EFAULT path points outside your accessible address space. 
ENAMETOOLONG path is too long. 
ENOENT The file does not exist. 


ENOMEM Insufficient kernel memory was available. 
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ENOTDIR A component of the path prefix is not a directory. 

EACCES Search permission is denied on acomponent of the path prefix. 

ELOOP path contains a circular reference (that is, via a symbolic link) 
SEE ALSO 

chdir(2) 


Linux 1.1.46, 21 August 1994 


clone 


clone— Creates a child process 


SYNOPSIS 


#include <linux/sched.h> 
#include <linux/unistd.h> 


pid t clone(void *sp, unsigned long flags); 


DESCRIPTION 
clone iS an alternate interface to fork, with more options. fork is equivalent to clone(@, SIGCLD!COPYVM). 
If sp isnonzero, the child process usessp asits initial stack pointer. 


Thelow byte of f! ags contains the signal sent to the parent when the child dies. f! ags may also be bitwise ored with either or 
both of copyvm and copyrp. 


If copyvm is set, child pages are copy-on-write images of the parent pages. If copyvm isnot set, the child process shares the same 
pages as the parent, and both parent and child may write on the same data. 


If copyro is set, the child’s file descriptors are copies of the parent's file descriptors. If copvrp isnot set, the child’s file 
descriptors are shared with the parent. 
RETURN VALUE 


On success, the PID of the child process is returned in the parent’s thread of execution, and a is returned in the child’s 
thread of execution. On failure a -1 will be returned in the parent’s context, no child process will be created, and errno will 
be set appropriately. 


ERRORS 
ENOSYS clone will always return this error, unless your kernel was compiled with 
CLONE_ACTUALLY_WORKS_OK defined. 
EAGAIN fork cannot allocate sufficient memory to copy the parent’s page tables and allocate a task 
structure for the child. 
BUGS 


By default, CLONE_ACTUALLY_WoRKS_OK iSnot defined. 
There isno entry for clone in /1ib/libc.so.4.5.26. 
Comments in the kernd as of 1.1.46 indicate that it mishandles the case where copyvm is not set. 


SEE ALSO 
fork(2) 
Linux 1.2.9, 10 June1995 
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close 
close— Closes a file descriptor 


SYNOPSIS 


#include <unistd.h> 
int close(int fd); 


DESCRIPTION 


close Closes a file descriptor so that it no longer refers to any file and may be reused. Any locks hdd on the file it was 
associated with, and owned by the process, are renoved (regardless of the file descriptor that was used to obtain the lock). 


If fd is the last copy of a particular file descriptor, the resources associated with it are freed; if the descriptor was the last 
reference to a file that has been removed using unlink, the file is deleted. 


RETURN VALUE 


close réturns @ on success, or -1 if an error occurred. 


ERRORS 


EBADF fd isn’t a valid open file descriptor. 


CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


NOTES 
N ot checking the return value of close isacommon but neverthdess serious programming error. File system implementa- 
tions that use techniques as write behind to increase performance may lead to wri t e(2) succeeding, although the data has not 
been written yet. T he error status may be reported at a later write operation, but it is guaranteed to be reported on closing 
the file. N ot checking the return value when closing the file may lead to silent loss of data. This can especially be observed 
with NFS and disk quotas. 


SEE ALSO 


open(2), fent1(2), shutdown(2), unlink(2), fclose(3) 
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connect 
connect— Initiates a connection on a socket 
SYNOPSIS 


#include <sys/types.h> 
#include <sys/socket.h> 
int connect(int sockfd, struct sockaddr *serv_addr ,intaddrlen); 


DESCRIPTION 
The parameter sockfd is a socket. If it isof type sock_peram, this call specifies the peer with which the socket is to be 
associated; this address is that to which datagrams are to be sent, and theonly address from which datagrams are to be 
received. If the socket is of type sock_stream, this call attenpts to make a connection to another socket. The other socket is 
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specified by serv_addr, which is an address in the communications space of the socket. Each communications space interprets 
the serv_addr, parameter in its own way. G erally, stream sockets may successfully connect only once; datagram sockets 
may use connect multiple times to change ther association. D atagram sockets may dissolve the association by connecting to 
an invalid address, such as a null address. 


RETURN VALUE 


If the connection or binding succeeds, o isreturned. On error, -1 is returned and errno is set appropriatay. 


ERRORS 


See the Linux kernel source code for details. 


HISTORY 
The connect function call first appeared in BSD 4.2. 


SEE ALSO 


accept(2), bind(2), listen(2), socket(2), getsockname(2) 
Linux 0.99.11, 23 July 1993 


dup, dup2 


dup, dup2— D uplicate a file descriptor 


SYNOPSIS 


#include <unistd.h> 
int dup(int oldfd); 
int dup2(int oldfd,intnewfd); 


DESCRIPTION 


dup and dup2 create a copy of the file descriptor o! dfd. 


Theold and new descriptors can be used interchangeably. T hey share locks, file position pointers and flags; for example if 
the file position is modified by using 1seek on one of the descriptors, the position is also changed for the othe. 


The two descriptors do not share the close on-exec flag, however. 
dup uses the lowest-numbered unused descriptor for the new descriptor. 
dup2 MakeSnewfd be the copy of ol dfd, Closingnewfd first if necessary. 


RETURN VALUE 
dup and dup2 return the new descriptor, or -1 if an error occurred (in which case errno is set appropriately). 
ERRORS 
EBADF ol dfd isn’t an open file descriptor, ornewfd is out of the allowed range for file descriptors. 
EMFILE The process already has the maximum number of file descriptors open and tried to op a 
new one. 
WARNING 
The eror returned by dup2 is different from that returned by fent1(...,F_DUPFD,...) When newfd is out of range On some 


systems dup2 also sometimes returns EINVAL like F_DUPFD. 
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CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 


fent1(2), open(2), close(2). 


execve 


execve— Execute program 


SYNOPSIS 


#include <unistd.h> 
int execve (const char *filename, const char *argv [], const char *envp[]); 


DESCRIPTION 


Linux 1.1.46, 21 August 1994 


execve() executes the program pointed to byfilename. filename must be either a binary executable or a shell script starting 


with alinein the format 4! interpreter [arg]. 


execve() does not return on success, and the text, data, bss, and stack of the calling process are overwritten by that of the 
program loaded. The program invoked inherits the calling process's PID , and any open file descriptors that are not set to 





close on exec. Signals pending on the parent process are cleared. 
If the current program is being ptraced, a statrap is sent to it after a successful execve(). 


RETURN VALUE 
On success, execve() does not return; on error -1 isreturned and errno is sé appropriately. 
ERRORS 
EACCES The file is not a regular file 
EACCES Execute permission is denied for the file 
EPERM The file system is mounted noexec. 
EPERM Thefile system is mounted nosuid and the filehas an SUID or SGID bit set. 
E2BIG Theargument list is too big. 
ENOEXEC The magic number in the file is incorrect. 
EFAULT filename points outside your accessible address space. 
ENAMETOOLONG filename is too long. 
ENOENT The file does not exist. 
ENOMEM Insufficient kernel memory was available. 
ENOTDIR A component of the path prefix is not a directory. 
EACCES Search permission is denied on acomponent of the path prefix. 
ELOOP filename contains a circular reference (that is, via a symbolic link). 
CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 
NOTES 


SUID and SGID processes can not be ptrace()’d SUID or SGID. 
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A maximum linelength of 127 charactersis allowed for thefirst linein a#! executable shell script. T his may be circum- 
vented by changing the max size of buf, in which case you will become bound by the 1024 byte size of a buffer, which is not 
easily worked around. 


SEE ALSO 


execl(3), fork(2) 


Linux 1.1.46, 21 August 1994 


fentl 


fent 


SYNOPSIS 


#inc 
#inc 
int 
int 


— M anipulate file descriptor 


ude <unistd.h> 

ude <fcntl.h> 

cntl(int fd,intcmd); 
cntl(int fd,intcmd,longarg); 


DESCRIPTION 


fent 





performs one of various miscellaneous operations on fd. The operation in question is determined by cmd: 


F_DUPFD M akesarg bea copy of fa, closing fd first if necessary. 


Thesame functionality can be more easily achieved by using dup2(2). 


The old and new descriptors may be used interchangeably. T hey share locks, file position 
pointers, and flags; for example, if the file position is modified by using 1seek on one of the 
descriptors, the position is also changed for the other. 


Thetwo descriptors do not share the close on-exec flag, however. 
On success, the new descriptor is returned. 


F_GETFD Read the close-on-exec flag. If the low-order bit is 0, the file will remain open across exec; 
otherwise, it will be closed. 

F_SETFD Sé& the close-on-exec flag to the value specified by arg (only the least significant bit 
is used). 

F_GETFL Read the descriptor’s flags (all flags— as set by open(2)— are returned). 

F_SETFL Se the descriptor’s flags to the value specified by arg. 


Only 0_APPEND and 0_NONBLOCK may be set. 


The flags are shared betwee copies (made with dup and so on) of the same file descriptor. 
The flags and their semantics are described in open(2). 


F_GETLK, F_SETLK, M anage discretionary filelocks. The third argument arg isa pointer to a struct flock 

and F_SETLKW (that may be overwritten by this call). 

F_GETLK Return theflock structure that prevents us from obtaining the lock, or set the 1 type field of 
thelock to F_uNLck if there is no obstruction. 

F_SETLK The lock isset (when 1 typeis F_RDLCK or F_wrLck) or Cleared (when it is F_UNLCK). 
If the lock is held by someone else this call returns -1 and sets errno to EACCES OF EAGAIN. 

F_SETLKW Like F_seTLK, but instead of returning an error, we wait for the lock to be released. 

F_GETOWN Get theprocess|D (or process group) of the owner of asocke.. 


Process groups are returned as negative values. 


F_SETOWN Set the process or process group that owns a socket. 


For these commands, ownership means receiving siGzo or s1G-urG signals. 
Process groups are specified using negative values. 
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RETURN VALUE 
Thereturn value depends on the operation: 
F_DUPFD Thenew descriptor. 
F_GETFD Value of flag. 
F_GETFL Value of flags. 
F_GETOWN Value of descriptor owner. 


On error, -1 isreturned and errno is s& appropriatdy. 


ERRORS 
EBADF fd isnot an open file descriptor. 
EINVAL For F_buPFD, arg is negative or is greater than the maximum allowable value. 
EMFILE For F_puprp, the process already has the maximum number of file descriptors open. 
NOTES 
Theerrors returned by dup2 are different from those returned by F_buPrp. 
CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 
SEE ALSO 


dup2(2), open(2), socket(2). 
Linux, 26 Seotenber 1995 


fdatasync 


fdatasync— Synchronizes afile’s in-core data with that on disk 


SYNOPSIS 


#include <unistd.h> 

#ifdef POSIX SYNCHRONIZED 10 
int fdatasync(int fd); 
#endif 


DESCRIPTION 


fdatasync flushes all data buffers of a file to disk (before the system call returns). It resembles fsync but is not required to 
update the metadata such as access time 

Applications that access databases or log files often write a tiny data fragment (for example onelinein alog file) and then 
Call fsync immediately in order to ensure that the written data is physically stored on the hard disk. Unfortunately, fsync will 
always initiate two write operations: one for the newly written data and another one in order to update the modification time 
stored in the inode If the modification time is not a part of thetransaction concept fdatasync can be used to avoid 
unnecessary inode disk write operations. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned and errno isse@t appropriately. 


flock 


ERRORS 


EBADF fd isnot a valid file descriptor open for writing. 
EROFS, EINVAL fd isbound to a special file which does not support synchronization. 
EIO An error occurred during synchronization. 


BUGS 


Currently (Linux 1.3.86) fdatasyne is equivalent to fsync. 


CONFORMS TO 
POSIX.4 


SEE ALSO 
fsync(2), B.O. Gallmaster, POSIX.4, O'Reilly, pp. 220-223, 343. 
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flock 


flock— Applies or removes an advisory lock on an open file 


SYNOPSIS 


#include <sys/file.h> 
int flock(int fd,intoperation) ; 


DESCRIPTION 


Apply or remove an advisory lock on an open file. The file is specified by #4. Valid operations aregiven hee 


LOCK_SH Shared lock. M ore than one process may hold a shared lock for a given file at a given time 

LOCK_EX Exclusive lock. O nly one process may hold an exclusive lock for a given file at a given time 

LOCK_UN Unlock. 

LOCK_NB Don’t block when locking. M ay be specified (by oring) along with one of the othe 
operations. 


A single file may not have both shared and exclusivelocks. A file is locked (that is, the 
inode), not the file descriptor. So, dup(2) and fork(2) do not create multiple instances 


of alock. 

RETURN VALUE 

On success, a isreturned. On error, -1 iSreturned and errno isset appropriately. 
ERRORS 

EWOULDBLOCK The file is locked and the Lock_ne flag was selected. 
NOTES 

Under Linux, flock isimplemented as a call to fent1. Please see fent1(2) for more details on errors. 
SEE ALSO 


open(2), close(2), dup(2), execve(2), fent1(2), fork(2) 


Linux 0.99.11, 22 July 1993 
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fork, vfork 


fork, vfork— Creates a child process 


SYNOPSIS 


#include <unistd.h> 
pid t fork(void); 
pid t vfork(void) ; 


DESCRIPTION 
fork Creates a child process that differs from the parent process only in its PID and PPID, and in the fact that resource 
utilizations are set to o. Filelocks and pending signals are not inherited. 


Under Linux, fork isimplemented using copy-on-write pages, so the only penalties incurred by fork are the time and 
memory required to duplicate the parent’s page tables and to create a unique task structure for the child. 


RETURN VALUE 


On success, the PID of the child process is returned in the parent’s thread of execution, and ao is returned in the child’s 
thread of execution. On failure a -1 will be returned in the parent’s context, no child process will be created, and errno will 
be set appropriately. 


ERRORS 
EAGAIN fork cannot allocate sufficient memory to copy the parent's page tables and allocate a task 
structure for the child. 
BUGS 
Under Linux, vfork ismerey an alias for fork. fork never returns the error ENOMEM. 
CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 
SEE ALSO 


clone(2), execve(2), wait(2) 
Linux 1.2.9, 10 June1995 


fsync 
fsync— Synchronizes a file's complete in-core state with that on disk 


SYNOPSIS 


#include <unistd.h> 
int fsync(int fd); 


DESCRIPTION 
fsync Copies all in-core parts of a file to disk. 
In some applications, fdatasync isa more efficient alternative to fsync. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned and errno isse@t appropriately. 


getdents 759 


ERRORS 


EBADF fd isnot a valid file descriptor open for writing. 
EROFS, EINVAL fd is bound to a special file that does not support synchronization. 
EIO An error occurred during synchronization. 


CONFORMS TO 
POSIX.1b 


SEE ALSO 


bdflush(2), fdatasync(2), sync(2), update(8), sync(8) 
Linux 1.3.85, 13 April 1996 


getdents 


getdents— Gets directory entries 


SYNOPSIS 


#include <unistd.h> 

#include <linux/dirent.h> 

#include <linux/unistd.h> 

syscall3(int, getdents, uint, fd, struct dirent *, dirp, uint, count); 
int getdents(unsigned int fd, struct dirent *dirp, unsigned int count ); 


DESCRIPTION 


getdents reads several dirent structures from the directory pointed at by fa into thememory area pointed to by dirp. The 
parameter count isthe size of the memory area. 


Thedirent structure is declared as follows: 


struct dirent 


af 
long d_ino; /* inode number */ 
off_t d_off; /* offset to next dirent */ 
unsigned short d_reclen; /* length of this dirent */ 
char d_name [NAME_MAX+1]; /* file name (null-terminated) */ 
} 


d_ino isan inodenumber. d_off isthe distance from the start of the directory to the start of the next dirent.d_recien isthe 
size of this entire dirent. d_name is anull-terminated filaaame 


This call supersedes readdir(2). 


RETURN VALUE 


On success, the number of bytes read is returned. On end of directory, a is returned. On error, -1 isreturned and errno is set 
appropriated y. 


ERRORS 

EBADF Invalid file descriptor fd. 

ENOTDIR File descriptor does not refer to a directory. 
SEE ALSO 


readdir(2), readdir(3) 
Linux 1.3.6, 22 July 1995 
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getdomainname, setdomainname 
getdomainname, setdomainname— Gets/sets domain name 


SYNOPSIS 


#include <unistd.h> 
int getdomainname(char *name, size t len); 
int setdomainname(const char *name, size_t len); 


DESCRIPTION 
T hese functions are used to access or to changethe domain name of the current processor. 
RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned and errno isset appropriately. 
ERRORS 
EINVAL For getdomainname, name points to NULL Or name iSlonger than | en. 
EPERM For setdomainname, the caller was not the superuser. 
EINVAL For setdomainname, | en was too long. 
CONFORMS TO 
POSIX does not specify these calls. 
BUGS 


getdomainname isnot compliant with other implementations because they always return | en bytes, even if name is longer. 
Linux, however, returns ErNnvaL in this case (as of DLL 4.4.1 libraries). 


NOTES 


Under Linux, getdomainname isimplenented at the library leve by calling uname(2). 


SEE ALSO 


gethostname(2), sethostname(2), uname(2) 


Linux 0.99.11, 22 July 1993 


getdtablesize 


getdtablesize— Gets descriptor table size 


SYNOPSIS 


#include <unistd.h> 
int getdtablesize(void) ; 


DESCRIPTION 


getdtablesize returns themaximum number of files a process can have open. 


NOTES 


getdtablesize isimplanented asa library function in DLL 4.4.1. This function returns open_max (set to 256 in Linux 
0.99.11) if opEN_max was defined when the library was compiled. O therwise, -1 is returned and errno is set to ENosys. 
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SEE ALSO 
close(2), dup(2), open(2) 
Linux 0.99.11, 22 July 1993 


getgid, getegid 
getgid, getegid— Gets group identity 


SYNOPSIS 
#include <unistd.h> 
gid_t getgid(void); 
gid_t getegid(void); 
DESCRIPTION 
getgid returns the real group ID of the current process. 
getegid returns the effective group ID of the current process. 
Thereal ID corresponds to the!D of the calling process. The effective|D correspondsto the set ID bit on thefile being 
executed. 
ERRORS 


T hese functions are always successful. 


CONFORMS TO 
POSIX, BSD 4.3 


SEE ALSO 


setregid(2), setgid(2) 
Linux 0.99.11, 23 July 1993 


getgroups, setgroups 


getgroups, setgroups— Gets/sets group access list 


SYNOPSIS 
#include <unistd.h> 
int getgroups(int size, gid t list[]); 
#define_USE_BSD 
#include <grp.h> 
int setgroups(size_t size, const gid t *list); 


DESCRIPTION 


getgroups Up to size supplemental groups are returned intist.Ifsize iso, list isnot modified, but 
the total number of supplemental groups for the process is returned. 


setgroups Sets the supplemental groups for the process. O nly the superuser may use this function. 
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RETURN VALUE 
getgroups On success, the number of groups stored in lit is returned (if size is@, however, the 
number of supplemental group IDs associated with the process isreturned). On error, -1 is 
returned and errno is set appropriatay. 
setgroups On success, a isreturned. On error, -1 iSreturned and errno is set appropriately. 
ERRORS 
EFAULT list hasan invalid address. 
EPERM For setgroups, the user is not the superuser. 
EINVAL For setgroups, gidsetsize iS greater than neroups (32 for Linux 0.99.11). 
CONFORMS TO 


getgroups conforms to PO SIX.1 (and ispresent in BSD 4.3). Since setgroups requires privilege it isnot covered under 
POSIX.1. 


BUGS 
Theuse sso flag probably shouldn’t be required for setgroups. 


SEE ALSO 
initgroups(3) 
Linux 0.99.11, 23 July 1993 


gethostid, sethostid 


gethostid, sethostid— Gets/sets the unique identifier of the current host 


SYNOPSIS 


#include <unistd.h> 


long int gethostid(void) ; 
int sethostid(long int hostid); 


DESCRIPTION 


Get or set a unique 32-bit identifier for the current machine. T he 32-bit identifier is intended to be unique among all UN 1X 
systems in existence. This normally resembles the Internet address for the local machine, as returned by gethostbyname(3), 
and thus usually never needs to be set. 


The sethostid Call is restricted to the superuser. 
Thehostid argument isstored in the file /etc/hostid. 


RETURN VALUES 


gethostid returns the 32-bit identifier for the current host as set by sethostid(2). 


CONFORMS TO 
POSIX.1 does not define these functions, but ISO/IEC 9945-1:1990 mentionsthem in B.4.4.1. 


FILES 


/etc/hostid 
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SEE ALSO 


hostid(1), gethostbyname(3) 
Linux 0.99.13, 29 N ovanber 1993 


gethostname, sethostname 


gethostname, sethostname— Gets/sets hostname 


#include <unistd.h> 
int gethostname(char *name, size t len); 
int sethostname(const char *name, size_t len); 


DESCRIPTION 
T hese functions are used to access or to change the hostname of the current processor. 
RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned and errno is set appropriately. 
ERRORS 
EINVAL len isnegative or, for sethostname, larger than the maximum allowed size For gethostname 
on Linux/i386, | en issmaller than the actual size. 
EPERM For sethostname, the caller was not the superuser. 
EFAULT name iS an invalid address. 
CONFORMS TO 
POSIX.1 does not define these functions, but ISO/IEC 9945-1:1990 mentions then in B.4.4.1. 
BUGS 


Some other implementations of gethostname successfully return | en bytes even if name is longer. Linux/Alpha complies with 
this behavior. Linux/i386, however, returns EINVAL in this case (as of DLL 4.6.27 libraries). 


NOTES 


Under Linux/Alpha, gethostname is asystem call. Under Linux/i386, gethostname isimplemented at the library leva by 
calling uname(2). 


SEE ALSO 


getdomainname(2), setdomainname(2), uname(2) 


Linux 1.3.6, 22 July 1995 


getitimer, setitimer 
getitimer, setitimer— Gets/sets value of an interval timer 


SYNOPSIS 


#include <sys/time.h> 
int getitimer(int which, struct itimerval *value); 
int setitimer(int which ,conststruct itimer-val *value, struct itimerval *ovalue); 
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DESCRIPTION 
The systen provides each process with three interval timers, each decrementing in a distinct time domain. When any timer 
expires, a signal issent to the process, and the timer (potentially) restarts. 
ITIMER_REAL Decremants in real time and delivers stcaLam upon expiration. 
ITIMER_VIRTUAL D ecrenents only when the process is executing, and delivers stavTALRm upon expiration. 
ITIMER_PROF D ecrenents both when the process executes and when the system is executing on behalf of 
the process. C oupled with 1TIMER_viRTUAL, this timer is usually used to profile the time 
spent by the application in user and kernd space. s1aproF is ddivered upon expiration. 
Timer values are defined by the following structures: 
struct itimerval { 
struct timeval it_interval; /* next value */ 
struct timeval it_value; /* current value */ 
}; 
struct timeval { 
long tv_sec; /* seconds */ 
long tv_usec; /* microseconds */ 
}; 
getitimer(2) fills the structure indicated by value with the current setting for the timer indicated by whi ch (one of 
ITIMER_REAL, ITIMER_VIRTUAL, OF ITIMER_PROF). The dement it_value is set to the amount of time renaining on the timer, or 
a if the timer is disabled. Similarly, it_interval is set to the reset value. setitimer(2) sets the indicated timer to the valuein 
value. If oval ue isnonzero, the old value of the timer is stored there. 
Timers decrement from it_value to , generate a signal, and reset toit_interval.A timer that is set to o(it_value isa orthe 
timer expires and it_interval iS@) stops. 
Bothtv_sec andtv_usec aresignificant in determining the duration of a timer. 
Timers will never expire before the requested time, instead expiring some short, constant time afterward, dependent on the 
system timer resolution (currently 10ms). U pon expiration, a signal will be generated and the timer reset. If the timer expires 
while the process is active (always true for 1TIMER_virT), the signal will be delivered immediately when generated. O therwise, 
the ddivery will be offset by a small time dependent on the system loading. 
RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned and errno is set appropriately. 
ERRORS 
EFAULT value and ovalue arenot valid pointers. 
EINVAL which iS not one Of ITIMER_REAL, ITIMER_VIRT, OF ITIMER_PROF. 
SEE ALSO 
gettimeofday(2), sigaction(2), signal (2) 
BUGS 


Under Linux, the gmeration and ddivery of asignal are distinct and there each signal is permitted only one outstanding 
event. It’s therefore concavable that under pathologically heavy loading, 1TIMER_REAL will expire before the signal from a 
previous expiration has been delivered. Thesecond signal in such an event will be lost. 


Linux 0.99.11, 5 August 1993 
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getpagesize 
getpagesize— Gets systan page size 


SYNOPSIS 


#include <unistd.h> 
size_t getpagesize(void) ; 


DESCRIPTION 


Returns thenumber of bytes in a page. T hisis the system’s page size, which is not necessarily the same as the hardware page 
size. 


NOTES 


getpagesize iSimplanented as alibrary function in DLL 4.4.1. D pending on what is defined when the library is compiled, 
this function returns EXEC_PAGESIZE (Set to 4096 in Linux 0.99.11), nBpa (set to 4096 in Linux 0.99.11), or naPc (not defined in 
Linux 0.99.11 or DLL 4.4.1 libraries). 


SEE ALSO 
sbrk(2) 
Linux 0.99.11, 23 July 1993 


getpeername 


getpeername— Gets the name of the connected peer 


SYNOPSIS 


int getpeername(int s, struct sockaddr *name,int*namel en); 


DESCRIPTION 


getpeername returns the name of the peer connected to sockets. Thenamel en parameter should be initialized to indicate the 
amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). The name is 
truncated if the buffer provided is too small. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isse& appropriately, 
ERRORS 
EBADF Theargument s isnot a valid descriptor. 
ENOTSOCK Thearguments isafile, not a socket. 
ENOTCONN The socket is not connected. 
ENOBUFS Insufficient resources were available in the system to perform the operation. 
EFAULT Thename parameter points to memory not in a valid part of the process address space. 
HISTORY 
The getpeername function call appeared in BSD 4.2. 
SEE ALSO 


accept(2), bind(2), getsockname(2) 
BSD Man Page 24 July 1993 
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getpid, getppid 
getpid, getppid— Gets process identification 


SYNOPSIS 


#include <unistd.h> 

pid_t getpid(void) ; 

pid_t getppid(void) ; 
DESCRIPTION 


getpid returns the process ID of the current process. (T hisis often used by routines that generate unique temporary 
filenames.) 


getppid returns the process!D of the parent of the current process. 


CONFORMS TO 
POSIX, BSD 4,3, SVID 


SEE ALSO 
exec(2), fork(2), kil1(2), mkstemp(3), tmpnam(3), tempnam(3), tmpfile(3) 
Linux 0.99.11, 23 July 1993 


getpriority, setpriority 
getpriority, setpriority— Gets/sets program scheduling priority 


SYNOPSIS 


#include <sys/time.h> 

#include <sys/resource.h> 

int getpriority(int which,int who); 

int setpriority(int which,int who,int prio); 


DESCRIPTION 


The scheduling priority of the process, process group, or user, as indicated by which and who, is obtained with the getpriority 
call and set with thesetpriority call. whi ch isOne of PRIO_PROCESS, PRIO_PGRP,Or PRIO_USER, and who iSinterpreted relative to 

whi ch (a process identifier for PRIo_PROCESS, process group identifier for pRIo_parP, and auser ID for prio_useR). A @ value of 

who Genotes the current process, process group, or user. prio isavaluein the range - 20 to 20. T he default priority is 0; lower 
priorities cause more favorable scheduling. 


The getpriority Call returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The 
setpriority Call sets the priorities of all the specified processes to the specified value. O nly the superuser may lower priorities. 
RETURN VALUES 


Because getpriority can legitimatey return the value -1, it is necessary to clear the external variable errno prior to the call, 
and then check it afterward to determine whether a-1 isan error or alegitimate value. The setpriority call returns @ if there 
isno error, or -1 if thereis. 


ERRORS 


ESRCH No process was located using thewhich and who values specified. 
EINVAL whi ch Was not one of PRIO_PROCESS, PRIO_PGRP,OF PRIO_USER. 
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In addition to these errors, setpriority will fail with the following: 


EPERM A process was located, but nether its effective nor real user |D matched the effective user ID 
of the caller. 
EACCES A nonsuperuser attempted to lower a process priority. 
HISTORY 
T hese function calls appeared in BSD 4.2. 
SEE ALSO 


nice(1), fork(2), renice(8) 
BSD Man Page 24 July 1993 


getrlimit, getrusage, setrlimit 


getrlimit, getrusage, setrlimit— Get/set resource limits and usage 


SYNOPSIS 


#include <sys/time.h> 
#include <sys/resource.h> 
#include <unistd.h> 


int getrlimit (int resource, struct rlimit *rlim); 
int getrusage (int who, struct rusage *usage); 
int setrlimit (int resource, const struct rlimit *rlim); 


DESCRIPTION 
getrlimit and setrlimit get and set resource limits. resource should be one of the following: 


RLIMIT CPU /* CPU time in seconds */ 

RLIMIT FSIZE /* Maximum filesize */ 

RLIMIT DATA /* max data size */ 

RLIMIT STACK /* max stack size */ 

RLIMIT CORE /* max core file size */ 

RLIMIT RSS /* max resident set size */ 

RLIMIT NPROC /* max number of processes */ 

RLIMIT NOFILE /* max number of open files */ 

RLIMIT MEMLOCK /* max locked-in-memory address space*/ 


A resource may be unlimited if you set the limit to RLIM_INFINITY, RLIMIT_OFILE isthe BSD name for RLIMIT_NOFILE. 


Theriimit structure is defined as follows : 


struct rlimit 
{ 

int rlim_cur; 

int rlim_max; 
}; 


getrusage returns the current resource usages for awho of either RUSAGE_SELF OF RUSAGE_CHILDREN: 


struct rusage 
{ 
struct timeval ru_utime; /* user time used */ 
struct timeval ru_stime; /* system time used */ 
long ru_maxrss; /* maximum resident set size */ 
long ru_ixrss; /* integral shared memory size */ 


768 Part II: System Calls 





ong ru_idrss; /* integral unshared data size */ 
ong ru_isrss; /* integral unshared stack size */ 
ong ru_minflt; /* page reclaims */ 
ong ru_majflt; /* page faults */ 
ong ru_nswap; /* swaps */ 
ong ru_inblock; /* block input operations */ 
ong ru_oublock; /* block output operations */ 
ong ru_msgsnd; /* messages sent */ 
ong ru_msgrcv; /* messages received */ 
ong ru_nsignals; /* signals received */ 
ong ru_nvcsw; /* voluntary context switches */ 
ong ru_nivcsw; /* involuntary context switches */ 
}; 
RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isse&t appropriately. 
ERRORS 
EINVAL getrlimit OF setriimit is called with abad resource. getrusage iS called with a bad who. 
EPERM A nonsuperuser tries to use setrlimit() to increase the soft or hard limit above the current 
hard limit, or a superuser tries to increase RLIMIT_NOFILE above the current kernel maximum. 
CONFORMS TO 
BSD 4.3 
SEE ALSO 


ulimit(2), quota(2) 
Linux, 23 July 1993 


getsid 
getsid— Gets session |D 


SYNOPSIS 


#include <unistd.h> 
pid_t getsid(void) ; 


DESCRIPTION 


getsid(@) returns the session ID of the calling process. getsid(p) returns the session ID of the process with process!D p. 


ERRORS 


On error, -1 will be returned. The only error that can happen is esrcH, when no process with process!ID p was found. 


CONFORMS TO 


This call is Linux specific. 


SEE ALSO 


setsid(2) 
Linux 1.3.85, 11 April 1996 
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getsockname 


getsockname— Gets socket name 


SYNOPSIS 


int getsockname(int s_", struct sockaddr *" name ", int *" namelen ); 


DESCRIPTION 


getsockname returns the current name for the specified socket. Thenamel en parameter should be initialized to indicate the 
amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). 


RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned and errno is set appropriately. 
ERRORS 
EBADF Theargument s isnot a valid descriptor. 
ENOTSOCK Thearguments isafile, not a socket. 
ENOBUFS Insufficient resources were available in the system to perform the operation. 
EFAULT Thename parameter points to memory not in a valid part of the process address space 
HISTORY 
The getsockname function call appeared in BSD 4.2. 
BUGS 
N ames bound to sockets in the UNIX domain are inaccessible; getsockname returns a 0-length name. 
SEE ALSO 


bind(2), socket(2) 
BSD Man Page 24 July 1993 


getsockopt, setsockopt 


getsockopt, setsockopt— Get and set options on sockets 


SYNOPSIS 
#include <sys/types.h> 
#include <sys/socket.h> 
int getsockopt(int s ,intlevel ,intoptname,void*optval ,int*optlen); 
int setsockopt(int s,intlevel ,intoptname, const void *optval ,intoptlen); 


DESCRIPTION 


getsockopt and setsockopt manipulate the opti ons associated with a socket. O ptions may exist at multiple protocol levels; 
they are always present at the uppermost socket level. 


W hen manipulating socket options, thelevel at which the option resides and the name of the option must be specified. To 
manipulate options at the socket level, | evel is specified assoL_sockeT. To manipulate options at any other leva, the protocol 
number of the appropriate protocol controlling the option is supplied. For example to indicate that an option is to be 
interpreted by the TCP protocol, | eve! should be set to the protocol number of TCP; see getprotoent(3). 
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The parameters opt val and opt! en are used to access option values for setsockopt. For getsockopt they identify a buffer in 
which the value for the requested option(s) is to be returned. For getsockopt, opt! en isavalue result paramete,, initially 
containing the size of the buffer pointed to by optval , and modified on return to indicate the actual sizeof the value 
returned. If no option value is to be supplied or returned, opt val may be NULL. 


optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The 
include file <sys/socket. h> contains definitions for socket-leve options, described below. O ptionsat other protocol levels 
vary in format and name; consult the appropriate entries in section 4 of the manual. 


M ost socket-leva options utilize an int parameter for optval. For setsockopt, the parameter should benonzero to nablea 
boolean option, or 0 if the option is to be disabled. so LINGER USeSastruct linger parameter, defined in <li nux/socket. h>, 
which specifies the desired state of the option and the linger interval (see bdow). so_sNDTIMEO and SO_RCVTIMEO US@astruct 

timeval parameter, defined in <sys/time.h>. 


The following options are recognized at the socket level. Except as noted, each may be examined with getsockopt and set 
with setsockopt: 





S0_DEBUG Enables recording of debugging information. 
SO_REUSEADDR Enables local address reuse. 

SO_KEEPALIVE Enables keep connections alive 

SO_DONTROUTE Enables routing bypass for outgoing messages. 
SO_LINGER Linger on close if data present. 

SO_BROADCAST Enables permission to transmit broadcast messages. 
$0_OOBINLINE Enables reception of out-of-band data in band. 
$0_SNDBUF Sets buffer size for output. 

$0_RCVBUF Sets buffer size for input. 

SO_SNDLOWAT Sets minimum count for output. 

SO_RCVLOWAT Sets minimum count for input. 

SO_SNDTIMEO Sets time-out value for output. 

SO_RCVTIMEO Sets time-out value for input. 

SO_TYPE Gets the type of the socket (get only). 
SO_ERROR Gets and clears error on the socket (get only). 


S0_DEBUG enables debugging in the underlying protocol modules. 


SO_REUSEADDR indicates that the rules used in validating addresses supplied in abina(2) call should allow reuse of local 
addresses, 


SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to 
respond to these messages, the connection is considered broken and processes using the socket are notified via a sIGPIPE 
signal when attempting to send data. 


SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to 
the appropriate network interface according to the network portion of the destination address. 





SO_LINGER controls the action taken when unsent messages are queued on socket and aclose(2) is performed. If the socket 
promises reliable delivery of data and so_Lincer isset, the system will block the process on the close attempt until it is able to 
transmit the data or until it decides it isunableto ddiver the information (a time out period, termed the linger interval, is 
specified in the setsockopt call when so_LINGER is requested). If so LINGER is disabled and a close is issued, the system will 
process the closein a manner that allows the process to continue as quickly as possible. 


Thelinger structure is defined in <li nux/socket. n> as follows: 


struct linger { 
int l_onoff; /* Linger active */ 
int l_linger; /* How long to linger for */ 
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1_onoff indicates whether to linger. If it is set to 1, 1_linger contains the time in hundredths of seconds how long the process 
should linger to complete the close If 1_onoft is set to 0, the process returns immediately. 


The option so_BroapcasT requests permission to send broadcast datagrams on the socket. Broadcast was a privileged 
Operation in earlier versions of the system. With protocols that support out-of-band data, the so_ooBINLINE option requests 
that out-of-band data be placed in the normal data input queue as rece ved; it will then be accessible with recv or read calls 
without the msc_oos flag. Some protocols always behave as if this option is set. 


SO_SNDBUF and so_RCvBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The 
buffer size may be increased for high-volume connections or may be decreased to limit the possible backlog of incoming data. 
Thesysten places an absolute limit on these values. 


SO_SNDLOWAT iS an option to set the minimum count for output operations. M ost output operations process all of the data 
supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. N onblocking 
output operations will process as much data as permitted subject to flow control without blocking, but will process no data if 
flow control does not allow the smaller of thelow water mark value or the entire request to be processed. A select(2) 
Operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The 
default value for so_snpLowat is set to a convenient size for network efficiency, often 1024. 


SO_RCVLOWAT iS an option to set the minimum count for input operations. In general, receive calls will block until any 
(nonzero) amount of data is received, then return with the smaller of the amount available or the amount requested. T he 
default value for so_RcvLowaT is 1. If so_RcvLowaT is set to alarger value blocking receive calls normally wait until they have 
received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low 
water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. 





SO_SNDTIMEO iS an option to set a time-out value for output operations. It accepts astruct timeval parameter with the 
number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked 
for this much time, it returns with a partial count or with the error ewouLpsLock if no data were sent. In the current 
implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies 
to output portions ranging in size from the low water mark to the high water mark for output. 


SO_RCVTIMEO is an option to set a time-out value for input operations. It accepts astruct timeval parameter with thenumber 
of seconds and microseconds used to limit waits for input operations to complete In the current implementation, this timer 
is restarted each time additional data are received by the protocol, and thus the limit isin effect an inactivity timer. Ifa 
receive operation has been blocked for this much time without rece ving additional data, it returns with a short count or with 
the error EwouLpBLock if no data were received. 


Finally, so_TyPe and so_error are options used only with setsockopt. 
so_Type returns the type of the socket, such aS sock_sTREAM; it is useful for servers that inherit sockets on startup. 


$o_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors 
on connected datagram sockets or for other asynchronous errors. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isse&t appropriately. 
ERRORS 
EBADF Theargument s isnot a valid descriptor. 
ENOTSOCK Theargument s isafile, not a socket. 
ENOPROTOOPT The option is unknown at the levd indicated. 
EFAULT The address pointed to by optva! isnotin a valid part of the process address space For 


getsockopt, this error may also be returned if optlen isnot in a valid part of the process 
address space. 
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HISTORY 
T hese system calls appeared in BSD 4.2. 


BUGS 


Several of the socket options should be handled at lower levels of the system. 


SEE ALSO 


ioct1(2), socket(2), getprotoent(3), protocols(5) 
BSD Man Page, 22 April 1996 


gettimeofday, settimeofday 


gettimeofday, settimeofday— G et/set time 


SYNOPSIS 


#include <sys/time.h> 
#include <unistd.h> 


int gettimeofday(struct timeval *tv, struct timezone *tz); 
int settimeofday(const struct timeval *tv , const struct timezone *tz); 


DESCRIPTION 
gettimeofday and settimeofday can se the time as well asatimezone tv iSatimeval struct, aS specified in /usr/include/ 
sys/time.h: 
struct timeval { 
long tv_sec; /* seconds */ 
long tv_usec; /* microseconds */ 
hs 


and tz is a timezone: 


struct timezone { 
int tz_minuteswest; 
/* minutes west of Greenwich */ 
int tz_dsttime; 
/* type of dst correction */ 
hs 


with daylight savings times defined as follows: 


DST_NONE /* not on dst */ 
DST_USA /* USA style dst */ 
DST_AUST /* Australian style dst */ 
DST_WET /* Western European dst */ 
DST_MET /* Middle European dst */ 
DST_EET /* Eastern European dst */ 
DST_CAN /* Canada */ 
DST_GB /* Great Britain and Eire */ 
DST_RUM /* Rumania */ 
DST_TUR /* Turkey */ 


DST_AUSTALT /* Australian style with shift in 1986 */ 
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And the following macros are defined to operate on this: 


#define timerisset(tvp) \ 
((tvp)->tv_sec || (tvp) ->tv_usec) 


#define timercmp(tvp, uvp, cmp)\ 
((tvp)->tv_sec cmp (uvp)->tv_sec |1\ 
(tvp) ->tv_sec == (uvp)->tv_sec &&\ 
(tvp)->tv_usec cmp (uvp) ->tv_usec) 
#define timerclear(tvp) 
((tvp)->tv_sec = (tvp)->tv_usec = 0) 


If either tv ortz isnull, the corresponding structure isnot set or returned. 
Only the superuser can use settimeofday. 


ERRORS 


EPERM settimeofday is called by someone other than the superuser. 
EINVAL Time zone (or something dse) is invalid. 


CONFORMS T0 
BSD 4.3 


SEE ALSO 


date(1), adjtimex(2), time(2), ctime(3), ftime(3) 
Linux 1.2.4, 15 April 1995 


getuid, geteuid 
getuid, geteuid— Get user identity 


SYNOPSIS 


#include <unistd.h> 
uid_t getuid(void) ; 
uid_t geteuid(void); 


DESCRIPTION 
getuid returns thereal user 1D of the current process. 
geteuid returns the effective user ID of the current process. 
Thereal ID corresponds to the!D of the calling process. The effective|D correspondsto the set ID bit on thefile being 
executed. 
ERRORS 


T hese functions are always successful. 


CONFORMS TO 
POSIX, BSD 4.3 


SEE ALSO 


setreuid(2), setuid(2) 
Linux 0.99.11, 23 July 1993 


774 Part II: System Calls 


idle 
idle— M akes process 0 idle 


SYNOPSIS 


#include <unistd.h> 
void idle(void) ; 


DESCRIPTION 


idle isan internal system call used during bootstrap. It marks the process's pages as swappable, lowers its priority, and enters 
the main scheduling loop. idle never returns. 


Only process 0 may call idle. Any user process, even a process with superuser permission, will receive EPERM. 


RETURN VALUE 

idle never returns for process 0, and always returns -1 for a user process. 
ERRORS 

EPERM Always, for a user process. 


Linux 1.1.46, 21 August 1994 


ioctl 


ioctl— Controls devices 


SYNOPSIS 


#include <sys/ioctl.h> 
int ioctl(int d,intrequest, ...); 


(The “third” argument istraditionally char *argp and will beso named for this discussion.) 


DESCRIPTION 
The ioct1 function manipulates the underlying device parameters of special files. In particular, many operating characteris- 
tics of character special files (for example, terminals) may be controlled with ioct1 requests. The argument ¢ must be an open 
file descriptor. 
AN ioctl request has encoded in it whether the argument is an in parameter or out parameter, and the size of the argument 
argp in bytes. M acros and defines used in specifying an ioctl request arelocated in the file <sys/ioct!.h>. 


RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned and errno isset appropriately. 
ERRORS 
EBADF d isnot a valid descriptor. 
ENOTTY d is not associated with a character special device. 
ENOTTY The specified request does not apply to the kind of object that the descriptor d references. 
EINVAL request Ofargp iSnot valid. 
HISTORY 


An ioct1 function call appeared in version 7 AT&T UNIX. 
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SEE ALSO 
execve(2), fent1(2), mt(4), sd(4), tty(4) 


INTRODUCTION 


Thisis iocti List 1.3.27, alist of iocti calls in Linux/i386 kernel 1.3.27. It contains 421 ioctis from /usr/include/ 
fasm, linuxg/*.h. For each ioct1, you'll find the numerical value, name, and argument type. 


An argument type of const struct foo * meansthe argument is input to thekerndl. struct foo * meansthe kernel outputs 
the argument. If the kernel uses the argument for both input and output, this is marked with // 1-0. 


Some ioct1s take more arguments or return more values than a single structure. T hese are marked // more and are docu- 
mented further in a separate section. 


This list is incomplete It does not include 


M  ioctis defined internal to the kernel (scsi ioct1.h). 
HM ioctis defined in modules distributed separately from the kernel. 


And, of course, | may have errors and omissions. 


Please email changes and comments to mec@duracef.shout.net. | am particularly interested in loadable modules that define 
their own ioctis. If you know of such amodule, tdl me where! can ftp it, and I'll include its ioctis in my next rdease. 


MAIN TABLE 


<include/asm-i386/socket. h> 





0x00008901 FIOSETOWN const int * 
0x00008902 SIOCSPGRP const int * 
0x00008903 FIOGETOWN int * 
0x00008904 SIOCGPGRP int * 
0x00008905 SIOCATMARK int * 
0x00008906 SIOCGSTAMP timeval * 





<include/asm-i386/termios. h> 











0x00005401 TCGETS struct termios * 
0x00005402 TCSETS const struct termios * 
0x00005403 TCSETSW const struct termios * 
0x00005404 TCSETSF const struct termios * 
0x00005405 TCGETA struct termio * 
0x00005406 TCSETA const struct termio * 
0x00005407 TCSETAW const struct termio * 
0x00005408 TCSETAF const struct termio * 
0x00005409 TCSBRK int 

0x0000540A TCXONC int 

0x0000540B TCFLSH int 

0x0000540C TIOCEXCL void 

0x0000540D TIOCNXCL void 

0x0000540E TIOCSCTTY int 

0x0000540F TIOCGPGRP pid_t * 


0x00005410 TIOCSPGRP const pid_t * 
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<include/asm-i386/termios. h> 





0x00005411 TIOCOUTQ int * 

0x00005412 TIOCSTI const char * 
0x00005413 TIOCGWINSZ const struct winsize * 
0x00005414 TIOCSWINSZ struct winsize * 
0x00005415 TIOCMGET int * 

0x00005416 TIOCMBIS const int * 

0x00005417 TIOCMBIC const int * 

0x00005418 TIOCMSET const int * 

0x00005419 TIOCGSOFTCAR int * 

0xQ000541A TIOCSSOFTCAR const int * 

0x0000541B FIONREAD int * 

0x0000541B TIOCINQ int * 

0x0000541C TIOCLINUX const char * 
0x0000541D TIOCCONS void 

OxQ000541E TIOCGSERIAL struct serial_strucct * 
0x0000541F TIOCSSERIAL const struct serial_strucct * 
0x00005420 TIOCPKT const int * 

0x00005421 FIONBIO const int * 

0x00005422 TIOCNOTTY void 

0x00005423 TIOCSETD const int * 

0x00005424 TIOCGETD int * 

0x00005425 TCSBRKP int 

0x00005426 TIOCTTYGSTRUCT struct tty_strucct * 
0x00005450 FIONCLEX void 

0x00005451 FIOCLEX void 

0x00005452 FIOASYNC const int * 

0x00005453 TIOCSERCONFIG void 

0x00005454 TIOCSERGWILD int * 

0x00005455 TIOCSERSWILD const int * 

0x00005456 TIOCGLCKTRMIOS struct termios * 
0x0005457 TIOCSLCKTRMIOS const struct temios * 
0x00005458 TIOCSERGSTRUCT struct async_strucct * 
0x00005459 TIOCSERGETLSR int. * 

0x0000545A TIOCSERGETMULTI struct serial_multiport_strucct * 
0x0000545B TIOCSERSETMULTI const struct serial_multiport_strucct * 





<include/linux/ax25. h> 





0x000089E0 SIOCAX25GETUID const struct sockaddr_ax25 * 
0x000089E1 SIOCAX25ADDUID const struct sockaddr_ax25 * 
0x000089E2 SIOCAX25DELUID const struct sockaddr_ax25 * 


0x000089E3 SIOCAX25NOUID const int * 


<include/linux/ax25. h> 
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0x000089E4 SIOCAX25DIGCTL const int * 
0xQ00089E5 SIOCAX25GETPARMS struct ax25_parms_strucct * // I-0 
0xQ00089E6 SIOCAX25SETPARMS const struct ax25_parms-struct * 
<include/linux/cdk. h> 
0x00007314 STL_BINTR void 
0x00007315 STL_BSTART void 
0x00007316 STL_BSTOP void 
0x00007317 STL_BRESET void 
<include/linux/ cdrom. h> 
0x00005301 CDROMPAUSE void 
0x00005302 CDROMRESUME void 
0x00005303 CDROMPLAYMSF const struct cdrom_msf * 
0x00005304 CDROMPLAYTRKIND const struct cdrom_ti * 
0x00005305 CDROMREADTOCHDR struct cdrom_tochdr * 
0x00005306 CDROMREADTOCENTRY struct cdrom_tocentry *// I-0 
0x00005307 CDROMSTOP void 
0x00005308 CDROMSTART void 
0x00005309 CDROMEJECT void 
0x0000530A CDROMVOLCTRL const struct cdrom_volctrl * 
0x0000530B CDROMSUBCHNL struct cdrom_subchnl * // I-0 
0x0000530C CDROMREADMODE2 const struct cdrom_msf * // MORE 
0x0000530D CDROMREADMODE1 const struct cdrom_msf * // MORE 
0x0000530E CDROMREADAUD 10 const struct cdrom_read_audio * 
0x0000530F CDROMEJECT SW int 
0x00005310 CDROMMULTISESSION struct cdrom_multisession * // I-0 
0x00005311 CDROM_GET_UPC struct f char [8]; g * 
0x00005312 CDROMRESET void 
0x00005313 CDROMVOLREAD struct cdrom_volctrl * 
0x00005314 CDROMREADRAW const struct cdrom_msf * // MORE 
0x00005315 CDROMREADCOOKED const struct cdrom_msf * // MORE 
0x00005316 CDROMSEEK const struct cdrom_msf * 








<include/linux/cm206. h> 


0x00002000 
0x00002001 


CM2@6CTL_GET_STAT 
CM2@6CTL_GET_LAST_STAT 


int 


int 
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<include/linux/cyclades. h> 





























0x00435901 CYGETMON struct cyclades_monitor * 
0x00435902 CYGETTHRESH int * 
0x00435903 CYSETTHRESH in 
0x00435904 CYGETDEFTHRESH int * 
0x00435905 CYSETDEFTHRESH in 
0x00435906 CYGETTIMEOUT int * 
0x00435907 CYSETTIMEOUT in 
0x00435908 CYGETDEFTIMEOUT int, * 
0x00435909 CYSETDEFT IMEOUT in 
<include/linux/ext2 fs. h> 
0x80046601 EXT2_I10C_GETFLAGS int, * 
0x40046602 EXT2_I0C_SETFLAGS const int * 
0x80047601 EXT2_I0C_GETVERSION int * 
0x40047602 EXT2_I0C_SETVERSION const int * 
<include/linux/fd. h> 
0x00000000 FDCLRPRM void 
0x00000001 FDSETPRM const struct floppy_struct * 
0x00000002 FDDEFPRM const struct floppy_struct * 
0x00000003 FDGETPRM struct floppy_struct * 
0x00000004 FDMSGON void 
0x00000005 FDMSGOFF void 
0x00000006 FDFMTBEG void 
0x00000007 FDFMTTRK const struct format_descr * 
0x00000008 FDFMTEND void 
0x0000000A FDSETEMSGTRESH int 
0x0000000B FDFLUSH void 
0x0000000C FDSETMAXERRS const struct floppy_max_errors * 
0x0000000E FDGETMAXERRS struc oppy_max_errors * 
0x00000010 FDGETDRVTYP struc char [16]; g * 
0x00000014 FDSETDRVPRM const struct floppy_drive_params * 
0x00000015 FDGETDRVPRM struc oppy_drive_params * 
0x00000016 FDGETDRVSTAT struc oppy_drive_struct * 
0x00000017 FDPOLLDRVSTAT struc oppy_drive_struct * 
0x00000018 FDRESET int 
0x00000019 FDGETFDCSTAT struc oppy_fdc_state * 
0x0000001B FDWERRORCLR void 
0x0000001C FDWERRORGET struc oppy_write_errors * 
Q@x0000001E FDRAWCMD struc oppy_raw_cmd * // MORE // I-0 


0x00000028 FDTWADDLE void 





<include/linux/fs.h> 
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0x0000125D 
0x0000125E 
0x0000125F 
0x00001260 
0x00001261 
0x00001262 
0x00001263 
0x00000001 
0x00000002 


LKROSET 
LKROGET 
LKRRPART 


LKFLSBUF 


B 

B 

B 
BLKGETSIZE 
B 

BLKRASET 

B 





LKRAGET 
FIBMAP 
FIGETBSZ 


const int * 
int * 

void 
int * 
void 
in 
int * 


int * // 1-0 





int * 





<include/linux/hdreg. h> 





0x00000301 
0x00000302 
0x00000304 
0x00000307 
0x00000308 
0x00000309 
0x0000030A 
0x0000030B 
0x0000031F 
0x00000321 
0x00000322 
0x00000323 
0x00000324 
0x00000325 
0x00000326 


HDIO_GETGEO 
HDIO_GET_UNMASKINTR 
HDIO_GET_MULTCOUNT 
HDIO_GET_IDENTITY 
HDIO_GET_KEEPSETTINGS 
HDIO_GET_CHIPSET 
HDIO_GET_NOWERR 
HDIO_GET_DMA 
HDIO_DRIVE_CMD 
HDIO_SET_MULTCOUNT 
HDIO_SET_UNMASKINTR 
HDIO_SET_KEEPSETTINGS 
HDIO_SET_CHIPSET 
HDIO_SET_NOWERR 





HDIO_SET_DMA 


struct hd geometry * 
int * 

int * 

struct hd driveid * 
int * 

int * 

int * 

int * 

int * // 1-0 

in 
in 
int 
in 


in 





in 





<include/linux/if eqgl.h> 





0x000089F0 
0x000089F1 
0x000089F2 
0x000089F3 
0x000089F4 
0x000089F5 


EQL_ENSLAVE 
EQL_EMANCIPATE 
EQL_GETSLAVECFG 
EQL_SETSLAVECFG 
EQL_GETMASTRCFG 
EQL_SETMASTRCFG 


struct ifreq * // MORE 
struct ifreq * // MORE 
struct ifreq * // MORE 
struct ifreq * // MORE 
struct ifreq * // MORE 
struct ifreq * // MORE 


// 
// 
// 
// 
// 


oo Oo Oo Oo LO 





<include/linux/if plip. h> 





0x000089F0 


SIOCDEVPLIP 


struct ifregq * // I-0 
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<include/linux/if ppp. h> 








0x00005490 PPPIOCGFLAGS int * 

0x00005491 PPPIOCSFLAGS const int * 
0x00005492 PPPIOCGASYNCMAP int * 

0x00005493 PPPIOCSASYNCMAP const int * 
0x00005494 PPPIOCGUNIT int * 

0x00005495 PPPIOCSINPSIG const int * 
0x00005497 PPPIOCSDEBUG const int * 
0x00005498 PPPIOCGDEBUG Ent: * 

0x00005499 PPPIOCGSTAT struct ppp_stats * 
0x0000549A PPPIOCGTIME struct ppp_ddinfo * 
0x0000549B PPPIOCGXASYNCMAP struct f int [8]; g * 
0x0000549C PPPIOCSXASYNCMAP const struct f int [8]; g * 
0x0000549D PPPIOCSMRU const int * 
0x0000549E PPPIOCRASYNCMAP const int * 
0x0000549F PPPIOCSMAXCID const int * 





<include/linux/ipx.h> 





0x000089EO SIOCAIPXITFCRT const char * 
0x000089E1 SIOCAIPXPRISLT const char * 
0x000089E2 SIOCIPXCFGDATA struct ipx_config_ data * 





<include/linux/kd. h> 





0x00004B60 GIO_FONT struct f char [8192]; g * 

0x00004B61 PIO_FONT const struct f char [8192]; g * 
0x00004B6B GIO_FONTX struct console_font_desc * // MORE I-0 
0x00004B6C PIO_FONTX const struct console_font_desc * //MORE 
0x00004B70 GIO_CMAP struct f char [48]; g * 

0x00004B71 PIO_CMAP const struct f char [48]; g 
0x00004B2F KIOCSOUND in 

0x00004B30 KDMKTONE in 

0x00004B31 KDGETLED char * 

0x00004B32 KDSETLED in 

0x00004B33 KDGKBTYPE char * 

0x00004B34 KDADDIO int // MORE 

0x00004B35 KDDELIO int // MORE 

0x00004B36 KDENABIO void // MORE 

0x00004B37 KDDISABIO void // MORE 

0x00004B3A KDSETMODE in 

0x00004B3B KDGETMODE int * 





0x00004B3C KDMAPDISP void // MORE 
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0x00004B3D KDUNMAPDISP void // MORE 
0x00004B40 GIO_SCRNMAP struct f char [E_TABSZ]; g * 
0x00004B41 PIO_SCRNMAP const struct f char [E_TABSZ]; g * 
0x00004B69 GIO_UNISCRNMAP struct f short [E_TABSZ]; g * 
@x00004B6A PIO_UNISCRNMAP const struct f short [E_TABSZ]; g * 
0x00004B66 GIO_UNIMAP struct unimapdesc * // MORE // I-0 
0x00004B67 PIO_UNIMAP const struct unimapdesc * // MORE 
0x00004B68 PIO_UNIMAPCLR const struct unimapinit * 
0x00004B44 KDGKBMODE int * 
0x00004B45 KDSKBMODE int 
0x00004B62 KDGKBMETA int * 
0x00004B63 KDSKBMETA int 
0x00004B64 KDGKBLED int * 
0x00004B65 KDSKBLED int 
0x00004B46 KDGKBENT struct kbentry * // I-0 
0x00004B47 KDSKBENT const struct kbentry * 
0x00004B48 KDGKBSENT struct kbsentry * // 1-0 
0x00004B49 KDSKBSENT const struct kbsentry * 
0x00004B4A KDGKBDIACR struct kbdiacrs * 
0x00004B4B KDSKBDIACR const struct kbdiacrs * 
0x00004B4C KDGETKEYCODE struct kbkeycode * // I-0 
0x00004B4D KDSETKEYCODE const struct kbkeycode * 
0x00004B4E KDSIGACCEPT int 
<include/linux/Ip. h> 
0x00000601 LPCHAR in 
0x00000602 LPTIME in 
0x00000604 LPABORT in 
0x00000605 LPSETIRQ in 
0x00000606 LPGETIRQ int * 
0x00000608 LPWAIT in 
0x00000609 LPCAREFUL in 
0x0000060A LPABORTOPEN in 
0x0000060B LPGETSTATUS int * 
0x0000060C LPRESET void 
0x0000060D LPGETSTATS struct lp stats * 
<include/linux/mroute. h> 
0x000089EO SIOCGETVIFCNT struct sioc_vif_req * // I-0 
0x000089E1 SIOCGETSGCNT struct sioc_sg req * // I-0 
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<include/linux/mtio. h> 





0x40086D01 MTIOCTOP const struct mtop * 
0x801C6D02 MTIOCGET struct mtget * 

0x80046D03 MTIOCPOS struct mtpos * 

0x80206D04 MTIOCGETCONF IG struct mtconfiginfo * 
0x40206D05 MTIOCSETCONF IG const struct mtconfiginfo * 





<include/linux/netrom. h> 





0x000089EO SIOCNRGETPARMS struct nr_parms_struct * // I-0 
0x000089E1 SIOCNRSETPARMS const struct nr_parms_struct * 
0x000089E2 SIOCNRDECOBS void 

0x000089E3 SIOCNRRTCTL const int * 





<include/linux/sbpcd. h> 





0x00009000 DDIOCSDBG const int * 
0x00005382 CDROMAUDIOBUFSIZ int 





<include/linux/scc.h> 





0x00005470 TIOCSCCINI void 

0x00005471 TIOCCHANINI const struct scc_modem * 
0x00005472 TIOCGKISS struct ioctl_command * // I-0 
0x00005473 TIOCSKISS const struct ioctl_command * 
0x00005474 TIOCSCCSTAT struct scc_stat * 





<include/linux/scsi.h> 





0x00005382 SCSI_IOCTL_GET_IDLUN struct f int [2]; 9 * 
0x00005383 SCSI_IOCTL_TAGGED_ENABLE void 

0x00005384 SCSI_IOCTL_TAGGED_DISABLE void 

0x00005385 SCSI_IOCTL_PROBE_HOST const int * // MORE 





<include/linux/smb fs.h> 





0x80027501 SMB_IOC_GETMOUNTUID uid t * 





<include/linux/sockios.h> 





0x0000890B SIOCADDRT const struct rtentry * // MORE 
0x0000890C SIOCDELRT const struct rtentry * // MORE 
0x00008910 SIOCGIFNAME char [] 

0x00008911 SIOCSIFLINK void 

0x00008912 SIOCGIFCONF struct ifconf * // MORE // I-0 
0x00008913 SIOCGIFFLAGS struct ifreq * // I-0 


0x00008914 SIOCSIFFLAGS const struct ifreq * 


<include/linux/sockios.h> 
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0x00008915 
0x00008916 
0x00008917 
0x00008918 
0x00008919 
0x0000891A 
0x0000891B 
0x0000891C 
0x0000891D 
0x0000891E 
0x0000891F 
0x00008920 
0x00008921 
0x00008922 
0x00008923 
0x00008924 
0x00008925 
0x00008926 
0x00008927 
0x00008929 
0x00008930 
0x00008931 
0x00008932 
0x00008940 
0x00008941 
0x00008950 
0x00008951 
0x00008952 
0x00008960 
0x00008961 
0x00008962 
0x00008970 
0x00008971 


SIOCGIFADDR 
SIOCSIFADDR 
SIOCGIFDSTADDR 
SIOCSIFDSTADDR 
SIOCGIFBRDADDR 
SIOCSIFBRDADDR 
SIOCGIFNETMASK 
SIOCSIFNETMASK 
SIOCGIFMETRIC 
SIOCSIFMETRIC 
SIOCGIFMEM 
SIOCSIFMEM 
SIOCGIFMTU 
SIOCSIFMTU 

OLD SIOCGIFHWADDR 
SIOCSIFHWADDR 
SIOCGIFENCAP 
SIOCSIFENCAP 
SIOCGIFHWADDR 
SIOCGIFSLAVE 
SIOCSIFSLAVE 
SIOCADDMULTI 
SIOCDELMULTI 
SIOCADDRTOLD 
SIOCDELRTOLD 
SIOCDARP 
SIOCGARP 
SIOCSARP 
SIOCDRARP 
SIOCGRARP 
SIOCSRARP 
SIOCGIFMAP 
SIOCSIFMAP 





struct ifregq * // I-0 
const struct ifreq * 
struct ifreq * // I-0 
const struct ifreq * 
struct ifreq * // I-0 
const struct ifreq * 
struct ifreq * // I-0 
const struct ifreq * 
struct ifreq * // I-0 
const struct ifreq * 
struct ifreq * // I-0 
const struct ifreq * 
struct ifreq * // I-0 


const struct ifreq * 








struct ifregq * // I-0 





const struct ifreq * // MORE 
int * 

const int * 

struct ifreq * // I-0 

void 

void 

const struct ifreq * 

const struct ifreq * 

void 
void 
const struct arpreq * 
struct arpreq * // I-0 
const struct arpreq * 
const struct arpreq * 
struct arpreq * // I-0 
const struct arpreq * 


struct ifreq * // I-0 





const struct ifreq * 





<include/linux/soundcard. h> 





0x00005100 
0x00005101 
0xC08C5102 
0xC0045103 
0x80045104 
0x80045105 
0x40045106 


SNDCTL_SEQ_RESET 
SNDCTL_SEQ_SYNC 
SNDCTL_SYNTH_INFO 
SNDCTL_SEQ_CTRLRATE 
SNDCTL_SEQ_GETOUTCOUNT 
SNDCTL_SEQ_GETINCOUNT 
SNDCTL_SEQ_PERCMODE 





void 

void 

struct synth_info * // I-0 
int * // 1-0 

int * 

int * 


void 
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<include/linux/soundcard. h> 





0x40285107 
0x40045108 
0x40045109 
0x8004510A 
0x8004510B 
0xC074510C 
0x4004510D 
0xC004510E 
0x4004510F 
OxCFB85110 
0x00005111 
0x40085112 
0xC0045401 
0x00005402 
0x00005403 
0x00005404 
0xC0045405 
0xC0045406 
0x40045407 
0x40045408 
OxCFB85001 
0xC0046D00 
0xC0046D01 
0xC0216D02 
0x00005000 
0x00005001 
0xC0045002 
0xC0045003 
0xC0045004 
0xC0045006 
0xC0045007 
0x00005008 
0xC0045009 
0xC004500A 
0x8004500B 
0xC0045005 
0x800C500C 
0x800C500D 
0x0000500E 
0x80045002 
0x80045006 
0x80045005 


SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 


SOUND_ 
SOUND_ 


SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 
SNDCT 


L FM LOAD INSTR 
L_SEQ_TESTMIDI 
L_SEQ_RESETSAMPLES 
L_SEQ_NRSYNTHS 
L_SEQ_NRMIDIS 
L_MIDI_INFO 
L_SEQ_ THRESHOLD 
L_SYNTH_MEMAVL 
L_FM_40P_ENABLE 
L_PMGR_ACCESS 
L_SEQ_PANIC 
L_SEQ_OUTOFBAND 
L_TMR_TIMEBASE 
L_TMR_START 
L_TMR_STOP 
L_TMR_CONTINUE 
L_TMR_TEMPO 
L_TMR_SOURCE 
L_TMR_METRONOME 
L_TMR_SELECT 
L_PMGR_IFACE 
L_MIDI_PRETIME 
L_MIDI_MPUMODE 
L_MIDI_MPUCMD 
L_DSP_RESET 
L_DSP_SYNC 
L_DSP_SPEED 
L_DSP_STEREO 
L_DSP_GETBLKSIZE 
PCM WRITE CHANNELS 
PCM WRITE FILTER 
L_DSP_POST 
L_DSP_SUBDIVIDE 
L_DSP_SETFRAGMENT 
L_DSP_GETFMTS 
L_DSP_SETFMT 
L_DSP_GETOSPACE 
L_DSP_GETISPACE 





L_DSP_NONBLOCK 


SOUND_PCM_READ RATE 
SOUND _PCM_READ CHANNELS 
SOUND _PCM_READ BITS 


const struct sbi_instrument * 
const int * 

const int * 

int * 

int * 

struct midi_info * // 1-0 

const int * 

int * // 1-0 

const int * 

struct patmgr_info * // 1-0 
void 

const struct seq_event_rec * 
int * // 1-0 

void 

void 

void 

int * // 1-0 

int * // 1-0 

const int * 

int * // 1-0 

struct patmgr_info * // 1-0 

int * // 1-0 

const int * 

struct mpu_command_rec * // 1-0 
void 

void 

int * // I- 
int * // I- 
int * // I- 
int * // I- 


oo oo. oo 6 


int * // I- 
void 

int * // I-0 

int * // I-0 

int * 

int * // I-0 

struct audio-buf-info * 
struct audio-buf-info * 
void 

int * 

int * 


int * 
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0x80045007 
0x00004300 
OxCFB04301 
0xC0144302 
0xC0144303 
0x40144304 
0x40144305 
0xC0144306 
0xC0144307 
Ox4FA44308 
Ox8FA44309 
0x80044D00 
0x80044D01 
0x80044D02 
0x80044D03 
0x80044D04 
0x80044D05 
0x80044D06 
0x80044D07 
0x80044D08 
0x80044D09 
0x80044D0A 
0x80044D0B 
0x80044D0C 
0x80044D0D 
0x80044D0E 
0x80044D0F 
0x80044D10 
0x80044D1C 
0x80044D1D 
Ox80044D1E 
0x80044DFF 
0x80044DFE 
0x80044DFD 
0x80044DFB 
0x80044DFC 
0xC0044D00 
0xC0044D01 
0xC0044D02 
0xC0044D03 
0xC0044D04 
0xC0044D05 


SOUND _PCM_READ FILTER 
SNDCTL_COPR_RESET 
SNDCTL_COPR_LOAD 
SNDCTL_COPR_RDATA 
SNDCTL_COPR_RCODE 
SNDCTL_COPR_WDATA 
SNDCTL_COPR_WCODE 
SNDCTL_COPR_RUN 
SNDCTL_COPR_HALT 
SNDCTL_COPR_SENDMSG 
SNDCTL_COPR_RCVMSG 
SOUND_MIXER_READ_VOLUME 
SOUND_MIXER_READ_BASS 
SOUND _MIXER_READ TREBLE 
SOUND_MIXER_READ_SYNTH 
SOUND_MIXER_READ PCM 
SOUND_MIXER_READ SPEAKER 
SOUND_MIXER_READ LINE 





SOUND _MIXER_READ MIC 
SOUND MIXER READ CD 
SOUND_MIXER_READ_IMIX 
SOUND _MIXER_READ ALTPCM 
SOUND _MIXER_READ RECLEV 
SOUND_MIXER_READ_IGAIN 
SOUND_MIXER_READ_OGAIN 
SOUND _MIXER_READ LINE1 
SOUND_MIXER_READ_LINE2 
SOUND_MIXER_READ LINES 
SOUND_MIXER_READ MUTE 
SOUND_MIXER_READ ENHANCE 
SOUND_MIXER_READ_LOUD 
SOUND_MIXER_READ_RECSRC 
SOUND_MIXER_READ_DEVMASK 
SOUND_MIXER_READ RECMASK 
SOUND_MIXER_READ_STEREODEVS 
SOUND_MIXER_READ_CAPS 
SOUND_MIXER_WRITE_VOLUME 
SOUND_MIXER_WRITE_BASS 
SOUND MIXER WRITE TREBLE 
SOUND_MIXER_WRITE_SYNTH 
SOUND_MIXER_WRITE_PCM 
SOUND_MIXER_WRITE_SPEAKER 


int 


void 


* 


const 


struc 


struc 


const 


const 


struc 


struc 


const 


struc 


int 
in 
int 
in 
in 
int 
in 
in 


in 





in 
int 
int 
in 
in 
in 
in 
in 
in 


int 





in 
int 
int 
int 
int 
int 
int 
int 
int 
int 
int 


int 


* 


* 


* 


* 





s 


c 


c 


s 


s 


c 


c 





Ss 


c 


// 
// 
// 
// 
// 


ruct copr_bu 
opr_debug_bu 
opr_debug_bu 


fer * 
lr ame a) 
* ff 1-0 


ruct copr_debug buf * 


ruct copr_debug_ buf * 


opr_debug_bu 
opr_debug_bu 





ay Fae) 
* // 1-0 


ruct copr_msg * 


opr_msg * 


ee ae es ee eg 
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<include/linux/soundcard. h> 





0xC0044D06 SOUND_MIXER_WRITE_LINE int * // 1-0 
0xC0044D07 SOUND_MIXER_WRITE_MIC int * // 1-0 
0xC0044D08 SOUND_MIXER_WRITE_CD int * // 1-0 
0xC0044D09 SOUND_MIXER_WRITE_IMIX int * // 1-0 
0xC0044D0A SOUND_MIXER_WRITE_ALTPCM Ink * ff T+ 
0xC0044D0B SOUND_MIXER_WRITE_RECLEV int * // 1-0 
0xC0044D0C SOUND_MIXER_WRITE_IGAIN int * // 1-0 
0xC0044D0D SOUND_MIXER_WRITE_OGAIN int * // 1-0 
OxC0044D0E SOUND_MIXER_WRITE_LINE1 int * // 1-0 
0xC0044D0F SOUND_MIXER_WRITE_LINE2 int * // 1-0 
0xC0044D10 SOUND_MIXER_WRITE_LINE3 int * ff 1-0 
OxC0044D1C SOUND_MIXER_WRITE_MUTE int * // 1-0 
0xC0044D1D SOUND_MIXER_WRITE_ENHANCE int * // 1-0 
OxCQ044D1E SOUND_MIXER_WRITE_LOUD int * // 1-0 
0xCQ044DFF SOUND_MIXER_WRITE_RECSRC int * // 1-0 





<include/linux/umsdos fs. h> 














0x000004D2 UMSDOS_READDIR_DOS struct umsdos_ioctl * // 1-0 
0x000004D3 UMSDOS_UNLINK_DOS const struct umsdos_ ioctl * 
0x000004D4 UMSDOS_RMDIR_DOS const struct umsdos_ ioctl * 
0x000004D5 UMSDOS_STAT_DOS struct umsdos_ioctl * // I-0 
0x000004D6 UMSDOS_CREAT_EMD const struct umsdos_ ioctl * 
0x000004D7 UMSDOS_UNLINK_EMD const struct umsdos_ ioctl * 
0x000004D8 UMSDOS_READDIR_EMD struct umsdos_ioctl * // 1-0 
0x000004D9 UMSDOS_GETVERSION struct umsdos_ioctl * 
@x000004DA UMSDOS_INIT_EMD void 

0x000004DB UMSDOS_DOS_SETUP const struct umsdos_ ioctl * 
0x000004DC UMSDOS_RENAME_DOS const struct umsdos_ ioctl * 





<include/linux/vt. h> 





0x00005600 VT_OPENGRY int * 

0x00005601 VT_GETMODE struct vt_mode * 
0x00005602 VT_SETMODE const struct vt_mode * 
0x00005603 VT_GETSTATE struct vt_stat * 
0x00005604 VT_SENDSIG void 

0x00005605 VT_RELDISP int 

0x00005606 VT_ACTIVATE int 

0x00005607 VT_WAI TACTI VE int 

0x00005608 VT_DISALLOCATE int 

0x00005609 VT_RESIZE const struct vt_sizes * 


0x0000560A VT_RESIZEX const struct vt_consize * 
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MORE ARGUMENTS 


Some ioct1s take a pointer to a structure that contains additional pointers. T hese are documented herein alphabetical order. 


CDROMREADAUDIO takes an input pointer const struct cdrom read audio *. The buf field points to an output buffer of length 
nframes * CD FRAMESIZE RAW. 


CDROMREADCOOKED, CDROMREADMODE1, CDROMREADMODE2, and CDROM-READRAW take an input pointer const struct cdrom msf *. T hey 
se the same pointer as an output pointer to char []. Thelength varies by request. For coRoMREADMODE1, most drivers use 
CD_FRAMESIZE, but the optics storage driver uses oPT BLOCKS1ZE instead (both have the numerical value 2048). 


c 





CDROMREADCOOKED char [CD_FRAMESIZE] 

CDROMREADMODE 1 char [CD_FRAMESIZE or OPT_BLOCKSIZE] 
CDROMREADMODE2 char [CD_FRAMESIZE_RAWO] 
CDROMREADRAW char [CD_FRAMESIZE_RAW] 

EQL_ENSLAVE, EQL_EMANCIPATE, EQL_GETSLAVECFG, EQL_SETSLAVECFG, EQL_GETMASTERCFG, and EQL_SETMASTERCFG take a struct 
ifreq *. Theifr data field isa pointer to another structure as follows: 
EQL_ENSLAVE const struct slaving request * 
EQL_EMANCIPATE const struct slaving request * 
EQL_GETSLAVECFG struct slave_config * // 1-0 
EQL_SETSLAVECFG const struct slave_config * 
EQL_GETMASTERCFG struct master_config * 
EQL_SETMASTERCFG const struct master_config * 





FDRAWCMD takes a struct floppy raw cmd *. If flags & FD RAW WRITE isnonzero, then data points to an input buffer of length 
length. If flags & FD RAW READ iSnonzero, then data points to an output buffer of length length. 


GIO_FONTX and PI0_FONTX take a struct console font desc * Of Aconst struct console font_desc *, respectivey. chardata 
points to a buffer of char [charcount]. This is an output buffer for aio_FonTx and an input buffer for pro_FoNTx. 


GIO_UNIMAP and PIo_UNIMAP take a struct unimapdesc * Of a const struct unimapdesc *, respectively. entries points toa 
buffer of struct unipair [entry ct]. Thisis an output buffer for aio_untmap and an input buffer for pro_UNTMaP. 


KDADDIO, KDDELIO, KDDISABIO, and KDENABIO enable or disable access to I/O ports. T hey are essentially alternate interfaces to 
ioperm. 


KDMAPDISP and KDUNMAPDISP enable or disable memory mappings or I/O port access. They are not implemented in the kernel. 


SCSI_IOCTL_PROBE_HOST takes an input pointer const int *, which isa length. It uses the same pointer as an output pointer to 
achar [] buffer of this length. 


SIOCADDRT and SIOcDELRT take an input pointer whose type depends on the protocol: 


M ost protocols const struct rtentry * 
AX.25 const struct ax25 route * 
NET/ROM const struct nr_route_struct * 


SIOCGIFCONF takeS a struct ifconf *. Theifc but field points to a buffer of leigth ifc 1en bytes, into which the kernel writes 
alist of type struct ifreq []. 


SIOCSIFHWADDR takes an input pointer whose type depends on the protocol: 
M ost protocols const struct ifreq * 
AX.25 const char [AX25_ADDR_LEN] 


TIOCLINUX takes a const char *.|It uses this to distinguish several independent subcases. In the following table, n + foo means 
foo after an N -byte pad. struct selection isimplicitly defined in drivers/char/selection.c: 
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TIOCLINUX-2 1 + const struct selection * 
TIOCLINUX-3 void 
TIOCLINUX-4 void 
TIOCLINUX-5 4 + const struct f long [8]; g * 
TIOCLINUX-6 char * 
TIOCLINUX-7 char * 
TIOCLINUX-10 1 + const char * 

DUPLICATE ioct1s 
This list does not include ioctis in the range SIOCDEVPRIVATE aNd SIOCPROTOPRIVATE: 
0x00000001 FDSETPRM FIBMAP 
0x00000002 FDDEFPRIM FIGETBSZ 
0x00005382 CDROMAUDIOBUFSIZ SCSI_IOCTL_GET_IDLUN 
0x00005402 SNDCTL_TMR_START TCSETS 
0x00005403 SNDCTL_TMR_STOP TCSETSW 
0x00005404 SNDCTL_TMR_CONTINUE TCSETSF 


Linux, 17 September 1995 


ioperm 
ioperm— Sets port input/output permissions 


SYNOPSIS 


#include <unistd.h> 
int ioperm(unsigned long from, unsigned long num,intturn_on); 


DESCRIPTION 


ioperm sets the port access permission bits for the process for num bytes starting from port address from to the value turn_on. 
The use of ioperm requires root privileges. 


Only the first 0x3ff 1/O ports can be specified in this manner. For more ports, the iop1 function must be used. Permissions 
are not inherited on fork, but on exec they are T his is useful for giving port access permissions to nonprivileged tasks. 


RETURN VALUE 


On success, a isreturned. On error, -1 iSreturned and errno is set appropriately. 


CONFORMS TO 


ioperm is Linux specific. 


SEE ALSO 
iop1(2) 
Linux, 21 January 1993 


1opl 


iopl1— Changes 1/0 privilege level 
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SYNOPSIS 


#include <unistd.h> 
int iopl(int level ); 


DESCRIPTION 
iop1 changes the I/O privilege level of the current process, as specified in! evel. 


This call is necessary to allow 8514-compatible X servers to run under Linux. Because these X servers require access to all 
65536 |/O ports, the ioperm call is not sufficient. 


In addition to granting unrestricted I/O port access, running at a higher I/O privilege leva also allows the process to disable 
interrupts. T his will probably crash the system and is not recommended. 


Thel/O privilege levd for anormal process is 0. 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned and errno isse& appropriately. 
ERRORS 

EINVAL level iS greater than 3. 

EPERM The current user is not the superuser. 


NOTES FROM THE KERNEL SOURCE 


iop1 has to be used when you want to access the 1/O ports beyond the Ox3ff range To ge the full 65536 ports bitmapped, 
you'd need 8KB of bitmaps/process, which isa bit excessive. 


SEE ALSO 


ioperm(2) 
Linux 0.99.11, 24 July 1993 


1pc 
ipe— System V IPC system calls 
SYNOPSIS 


int ipc(unsigned int call, int first, int second, 
int third, void *ptr, long fifth); 


DESCRIPTION 


ipe isacommon kernel entry point for the System V IPC calls for messages, semaphores, and shared memory. cal | 
determines which IPC function to invoke the other arguments are passed through to the appropriate call. 


User programs should call the appropriate functions by their usual names. O nly standard library implementors and kernd 
hackers need to Know about ipc. 


SEE ALSO 


msgct1(2), msgget(2), msgrcv(2), msgsnd(2), semct1(2), semget(2), semop(2), shmat(2), shmct1(2), shmdt(2), shmget(2) 
Linux 1.2.4, 15 April 1995 
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kill 
kill— Sends signal to a process 


SYNOPSIS 
#include <sys/types.h> 
#include <signal.h> 
int kill(pid t pid,intsig); 
DESCRIPTION 
The kill system call can beused to send any signal to any process group or process. 
If pid is positive, then signal sig issent to pid. In this case, @ isreturned on success and a negative value is returned on error. 


If pid equals -1, then sig is sent to every process except the first one, from higher numbers in the proc table to lower. In this 
case, a is returned on success, or the error condition resulting from signaling the last process is returned. 


If pid is less than -1, then sig is sent to every process in the process group - pid. In this case, the number of processes the 
signal was sent to is returned and a negative value is returned for failure. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isse@t appropriately. 
ERRORS 
EINVAL An invalid signal is sent. 
ESRCH The pia or process group does not exist. N ote that an existing process might bea zombie a 
process that already committed termination, but has not yet been wait()ed for. 
EPERM The effective userID of the process calling ki11() isnot equal to the effective use ID of pid, 
unless the superuser called ki11(). 
BUGS 


It isimpossible to send a signal to task number one, the init process, for which it has not installed a signal handler. T hisis 
doneto ensure that the system isnot brought down accidentally. 


CONFORMS TO 
SVID, AT&T, POSIX.1, X/OPEN, BSD 4.3 


SEE ALSO 
exit(2), exit(2), signal(2), signal (7) 
Linux, 1 N ovember 1995 


killpg 
killpg— Sends signal to a process group 


SYNOPSIS 


#include <signal.h> 
int killpg(int pgrp,intsig); 


DESCRIPTION 


killpg sends the signal sig to the process group pgr p. See sigaction(2) for alist of signals. If pgrp is, killpg sends the signal 
to the sending process's process group. 
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The sending process and members of the process group must have the same effective user ID, or the sander must be the 
superuser. As a single special case, the continue signal stacont may be sent to any process that is a descendant of the current 
process. 


RETURN VALUE 
On success, 0 is returned. On error, -1 is returned and errno isse& appropriately, 
ERRORS 
EINVAL sig isnot avalid signal number. 
ESRCH No process can be found in the process group specified by pgrp. 
ESRCH The process group was given ase, but the sending process does not have a process group. 
EPERM The sending process is not the superuser and one or more of the target processes has an 
effective user ID different from that of the sending process. 
HISTORY 
The killpg function call appeared in BSD 4.0. 
SEE ALSO 


kill(2), getpgrp(2), signal(2) 
BSD Man Page 23 July 1993 


link 
link— M akes anew name for afile 


SYNOPSIS 


#include <unistd.h> 
int link(const char *oldpath, const char *newpath); 


DESCRIPTION 
link creates a new link (also known as a hard link) to an existing file. 
If newpath exists, it will not be overwritten. 


This new name may be used exactly as the old one for any operation; both names refer to the same file (and so have the same 
permissions and ownership) and it is impossible to tell which name was the original. 








RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned and errno isset appropriately. 
ERRORS 

EXDEV oldpath and newpath arenot on the same filesystem. 

EPERM The filesystem containing ol dpath and newpath doesnot support the creation of hard links. 

EFAULT oldpath Ornewpath points outside your accessible address space. 

EACCES W rite access to the directory containingnewpath isnot allowed for the process's effective 
UID, or oneof thedirectoriesin ol dpath Ornewpath did not allow search (execute) 
permission. 

ENAMETOOLONG oldpath Ornewpath was too long. 

ENOENT A directory componentin ol dpath Or newpath does not exist or isa dangling symbolic link. 





ENOTDIR A component used as a directory in ol dpath Or newpath iSnot, in fact, a directory. 
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ENOMEM Insufficient kernel memory was available. 
EROFS Thefileis on a read-only filesystem. 
EEXIST newpath already exists, 
EMLINK Thefile referred to by ol dpath already hasthe maximum number of links to it. 
ELOOP oldpath Ornewpath Contains a reference to a circular symbolic link, that is, a symbolic link 
whose expansion contains a reference to itsdf. 
ENOSPC The device containing the file has no room for the new directory entry. 
EPERM oldpath isthe. or .. entry of a directory. 
NOTES 
H ard links, as created by 1ink, cannot span filesystems. U se symlink if thisis required. 
CONFORMS TO 
SVID, AT&T, POSIX, BSD 4.3 
BUGS 


On NFS file systems, the return code may be wrong in case the N FS server peformsthelink creation and dies before it can 
say SO. Use stat(2) to find out if the link was created. 
SEE ALSO 
symlink(2), unlink(2), rename(2), open(2), stat(2), 1n(1), 1ink(8) 
Linux, 17 August 1994 


listen 


listen— Listens for connections on a socket 


SYNOPSIS 


#include <sys/socket.h> 
int listen(int_s ,int backlog); 


DESCRIPTION 


To accept connections, asocket is first created with socket(2), a willingness to accept incoming connections and a queue 
limit for incoming connections are specified with listen, and then the connections are accepted with accept(2). The listen 
call applies only to sockets of type sock _STREAM OF SOCK_SEQPACKET. 


Thebackl og parameter defines the maximum length the queue of pending connections may grow to. If a connection request 
arrives with the queue full, the client might receive an error with an indication of ECoNNREFUSED, or, if the underlying protocol 
supports retransmission, the request may be ignored so that retries may succeed. 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned and errno isse&t appropriately. 
ERRORS 

EBADF Theargument s isnot a valid descriptor. 

ENOTSOCK The argument s isnot a socket. 

EOPNOTSUPP The socket is not of a type that supports the operation listen. 
HISTORY 


The listen function call appeared in BSD 4.2. 


BUGS 


If the socket is of type af_inet and the backlog argument is greater than 128, it is silently truncated to 128. For portable 
applications, don’t rely on this valuesince BSD (and at least some BSD -derived systems) limit the backlog to 5. 


SEE ALSO 


accept(2), connect(2), socket(2) 
BSD Man Page 23 July 1993 


llseek 


_l1seek— Repositions the read/write file offset 


SYNOPSIS 


#include <unistd.h> 

#include <linux/unistd.h> 

_syscall5(int, llseek, uint, fd, ulong, hi, ulong, lo, loff_t*,res,uint,wh); 
int llseek(unsigned int fd, unsigned long offset_high, 

unsigned long offset_low,loff_t * result , unsigned int whence); 


DESCRIPTION 


The_11seek function repositions the offset of the file descriptor fd to (offset_high<<32) | offset_low bytes rdative to the 
beginning of the file, the current position in the file, or the end of the file, deoending on whether whence iSSEEK_SET, 
SEEK_CUR,OF SEEK_END, respectively. It returns the resulting file position in the argument result. 


RETURN VALUES 


Upon successful completion, 11seek returns. O therwise, a value of -1 is returned and errno is set to indicate the error. 


ERRORS 


EBADF fd isnot an open file descriptor. 
EINVAL whence iSinvalid. 


CONFORMS TO 


This function is Linux specific. 


BUGS 


Thereis no support for files with a size of 2GB or more 


SEE ALSO 
lseek(2) 
Linux 1.2.9, 10 June1995 


lseek 


lseek— Repositions read/write file offset 


SYNOPSIS 


#include <unistd.h> 
off_t lseek(int fildes ,off_t offset ,int whence); 
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DESCRIPTION 


The 1seek function repositions the offset of the file descriptor fil des to the argument offset according to the directive 
whence. 1 he argument fildes must bean open file descriptor. 1seek repositions the file pointer fii des as follows: 


If whence iSSEEK_SET, the offset isset to offset bytes. 

If whence iSSEEK_cur, the offset is set to its current location plus offset bytes. 

If whence iSSEEK_END, the offset isset to the sizeof thefile plusoffset bytes. 

The 1seek function allows the file offset to be set beyond the end of the existing end-of-file of the file If data is later written 
at this point, subsequent reads of the datain the gap return bytes of zeros (until data is actually written into the gap). 
Some devices are incapable of seeking. T he value of the pointer associated with such a device is undefined. 


RETURN VALUES 


Upon successful completion, 1seek returns the resulting offset location as measured in bytes from the beginning of the file. 
Otherwise, a value of -1 is returned and errno is set to indicate the eror. 


ERRORS 


EBADF fildes isnotan open file descriptor. 
ESPIPE fildes iS associated with a pipe socket, or FIFO. 
EINVAL whence isnot a proper value 


CONFORMS TO 


POSIX, BSD 4.3 


BUGS 


This document's use of whence is incorrect English, but maintained for historical reasons. 


SEE ALSO 


dup(2), open(2), fseek(3) 
Linux 1.2.9, 10 June1995 


mkdir 


mkdir— Creates a directory 


SYNOPSIS 


#include <sys/types.h> 

#include <fcntl.h> 

#include <unistd.h> 

int mkdir(const char *pathname, mode t mode); 


DESCRIPTION 


mkdir attempts to create a directory named pathname. 


mode Specifies the permissions to use. It is modified by the process's umask in the usual way: the permissions of the created 
file is (mode & “umask). 


The newly created directory will be owned by the effective UID of the process. If the directory containing the file has the set 
group ID bit set, or if the filesystem is mounted with BSD group semantics, the new directory will inherit the group 
ownership from its parent; otherwise, it will be owned by the effective GID of the process. 


If the parent directory has the set group ID bit set, so will thenewly created directory. 


RETURN VALUE 
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mkdir returns @ on success, or -1 if an error occurred (in which case, errno is set appropriately). 


ERRORS 


EEXIST 
EFAULT 
EACCES 


ENAMETOOLONG 
ENOENT 
ENOTDIR 
ENOMEM 

EROFS 

ELOOP 


ENOSPC 
ENOSPC 


BUGS 


pathname already exists (not necessarily as a directory). 
pathname points outside your accessible address space. 


The parent directory does not allow write permission to the process, or one of the 
directories in pathname did not allow search (execute) permission. 


pathname was too long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 
A component used asa directory in pat hname isnot, in fact, a directory. 
Insufficient kernel memory was available. 

pathname refersto a file on aread-only filesystem and write access was requested. 


pathname Contains areference to a circular symbolic link, that is, a symbolic link whose 
expansion contains a reference to itself. 


The device containing pathname has no room for the new directory. 
Thenew directory cannot be created because the user’s disk quota is exhausted. 


In some older versions of Linux (for example, 0.99p!7) all the normal filesystems sometime allow the creation of two files in 
the same directory with the same name This occurs only rarely and only on aheavily loaded system. It is bdieved that this 
bug was fixed in the M inix filesystem in Linux 0.99pI8 prerelease and it is hoped that it was fixed in the other filesystems 


shortly afterward. 


There are many infdicities in the protocol underlying N FS. 


SEE ALSO 


read(2), write(2), font1(2), close(2), unlink(2), open(2), mknod(2), stat(2), umask(2), mount(2), socket(2), socket(2), fopen(3) 


mknod 


mknod— C reates a directory 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <unistd.h> 


Linux 1.0, 29 M arch 1994 


int mknod(const char *pathname, mode t mode,dev_t dev); 


DESCRIPTION 


mknod attempts to create a filesystem node (file, device special file, or named pipe) named pat hname, Specified by mode and dev. 


mode Specifies both the permissions to use and the type of node to be created. 
It should be a combination (using bitwise or) of one of the file types listed below and the permissions for the new node. 


The permissions are modified by the process's umask in the usual way: T he permissions of the created node is (mode & 


“umask). 
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The file type should be one of s_IFREG, S_IFCHR, $_IFBLK, OF $_IFIFO to specify anormal file (which will be created empty), 
character special file, block special file, or FIFO (named pipe), respectively, or 0, which will create a normal file. 


If the filetype iss_IFCHR Or S_IFBLK, then dev Specifies the major and minor numbers of the newly created device special file 
otherwise it isignored. 
Thenewly created node will be owned by the effectiveU ID of the process. If the directory containing the node has the set 


group ID bit set, or if the filesystem is mounted with BSD group semantics, the new nodewill inherit the group ownership 
from its parent directory; otherwise it will be owned by the effective GID of the process. 


RETURN VALUE 
mknod returns @ On success, or -1 if an error occurred (in which case, errno is set appropriately). 
ERRORS 
EPERM mode requested creation of something other than a FIFO (named pipe), and the caller is not 
the superuser; also returned if the filesystem containing pathname doesnot support thetype 
of node requested. 
EINVAL mode requested creation of something othe than a normal file device special file or FIFO. 
EEXIST pathname already exists, 
EFAULT pathname points outside your accessible address space. 
EACCES The parent directory does not allow write permission to the process, or one of the 
directories in pathname did not allow search (execute) permission. 
ENAMETOOLONG pathname was too long. 
ENOENT A directory component in pat hname does not exist or isa dangling symbolic link. 
ENOTDIR A component used asa directory in pathname isnot, in fact, a directory. 
ENOMEM Insufficient kernel memory was available. 
EROFS pathname refersto afile on aread-only filesystem and write access was requested. 
ELOOP pathname Contains a reference to acircular symbolic link, that is, a symbolic link whose 
expansion contains a reference to itself. 
ENOSPC Thedevicecontaining pat hname has no room for the new node 
BUGS 


In some older versions of Linux (for example, 0.99pI7) all the normal filesystems sometime allow the creation of two files in 
the same directory with the same name This occurs only rarely and only on aheavily loaded system. It is bdieved that this 
bug was fixed in the M inix filesystem in Linux 0.99p!8 prerelease and it is hoped that it was fixed in the other filesystems 
shortly afterward. 


mknod Cannot be used to create directories or socket files, and cannot be used to create normal files by users other than the 
superuser. 


There are many infdicities in the protocol underlying N FS. 


SEE ALSO 


read(2), write(2), fent1(2), close(2), unlink(2), open(2), mkdir(2), stat(2), umask(2), mount(2), socket(2), fopen(3) 
Linux 1.0, 29 M arch 1994 


mlock 


mlock— D isables paging for some parts of memory 
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SYNOPSIS 


#include <sys/mman.h> 
int mlock(const void *addr, size_t len); 


DESCRIPTION 


mlock disables paging for the memory in the range starting at addr with length | en bytes. All pages that contain a part of the 
specified memory range are guaranteed to be resident in RAM when themlock system call returns successfully and they are 
guaranteed to stay in RAM until the pages are unlocked again by munlock Or munlockall or until the process terminates or 
starts another program with exec. Child processes do not inherit page locks across a fork. 


M emory locking has two main applications: real-time algorithms and high-security data processing. Real-time applications 
require deterministic timing, and, like scheduling, paging is one major cause of unexpected program execution ddays. R eal- 
time applications will usually also switch to a real-time scheduler with sched setscheduler. 


Cryptographic security software often handles critical bytes such as passwords or secret keys as data structures. As a result of 
paging, these secrets could be transferred onto a persistent swap store medium, where they might be accessible to the eneny 
long after the security software has erased the secretsin RAM and terminated. 

M emory locks do not stack, that is, pages that have been locked several times by calls to mlock Or mlockal1 will be unlocked 
by asingle call to munlock for the corresponding range or by munlockall. Pages that are mapped to several locations or by 
several processes stay locked into RAM as long as they are locked at least at one location or by at least one process. 


On POSIX systems on which mlock and munlock are available _POSIX_MEMLOCK_RANGE iS defined in <unistd.h> and the value 
PAGESIZE from <limits.h> indicates the number of bytes per page. 


RETURN VALUE 


On success, mlock returns@. On error, -1 isreturned, errno is set appropriately, and no changes are made to any locksin the 
address space of the process. 


ERRORS 
ENOMEM Some of the specified address range does not correspond to mapped pages in the address 
space of the process or the process tried to exceed the maximum number of allowed locked 
pages. 
EPERM The calling process does not have appropriate privileges. O nly root processes are allowed to 
lock pages. 
EINVAL len WaSnot a positive number. 
STANDARDS 
POSIX.1b, SVR4 
SEE ALSO 


munlock(2), mlockall(2), munlockall(2). 
Linux 1.3.43, 26 November 1995 


mlockall 


mlockal1l— Disables paging for calling process 


SYNOPSIS 


#include <sys/mman.h> 
int mlockall(int flags); 
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DESCRIPTION 


mlockall disables paging for all pages mapped into the address space of the calling process. T his includes the pages of the 
code, data and stack segments, shared libraries, user space kernd data, shared memory, and memory-mapped files. All 
mapped pages are guaranteed to be resident in RAM when themlockal1 system call returns successfully and they are 
guaranteed to stay in RAM until the pages are unlocked again by munlock Or munlockall or until the process terminates or 
starts another program with exec. Child processes do not inherit page locks across a fork. 


M emory locking has two main applications: real-time algorithms and high-security data processing. Real-time applications 
require deterministic timing, and, like scheduling, paging is one major cause of unexpected program execution ddays. R eal- 
time applications will usually also switch to a real-time scheduler with sched setscheduler. Cryptographic security software 
often handles critical bytes such as passwords or secret Keys as data structures. As a result of paging, these secrets could be 
transferred onto a persistent swap store medium, where they might be accessible to the enemy long after the security software 
has erased the secretsin RAM and terminated. For security applications, only small parts of memory have to be locked, for 
which mlock is available. 


Thefl ags parameter can be constructed from the logical or of the following constants: 


MCL_CURRENT Lock all pages that are currently mapped into the address space of the process. 

MCL_FUTURE Lock all pages that will become mapped into the address space of the process in the future. 
These could be for instance, new pages required by a growing heap and stack as well as new 
memory mapped files or shared memory regions. 


If wcL_FUTURE has been specified and the number of locked pages exceeds the upper limit of allowed locked pages, the system 
call that caused the new mapping will fail with enomem. If these new pages have been mapped by the growing stack, the kernel 
will deny stack expansion and send a siGsecv. 


Real-time processes should reserve enough locked stack pages before entering the time-critical section, so no page fault can be 
caused by function calls. This can be achieved by calling afunction that has a sufficiently large automatic variable and that 
writes to the memory occupied by this large array in order to touch these stack pages. This way, enough pages will be 
mapped for the stack and can be locked into RAM. The dummy writes ensure that not even copy-on-write page faults can 
occur in the critical section. 


Memory locks do not stack, that is, pages that have been locked several times by calls to mlockal1 Or mlock will be unlocked 
by asingle call to munlocka11. Pages that are mapped to several locations or by several processes stay locked into RAM as long 
as they are locked at least at one location or by at least one process. 


On POSIX systems on which mlockall and munlockal1 are available, postx memLock is defined in <unistd.h>. 





RETURN VALUE 
On SUCCESS, mlockall returns @. On error, -1 iSreturned and errno is set appropriately. 
ERRORS 
ENOMEM The process tried to exceed the maximum number of allowed locked pages. 
EPERM The calling process does not have appropriate privileges. O nly root processes are allowed to 
lock pages. 
EINVAL Unknown flags were specified. 
STANDARDS 
POSIX.1b, SVR4 
SEE ALSO 


munlockall(2), mlock(2), munlock(2) 
Linux 1.3.43, 26 November 1995 
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mmap, munmap 


mmap, munmap— M ap or unmap files or devices into memory 


SYNOPSIS 


#include <unistd.h> 
#include <sys/mman.h> 
#ifdef POSIX MAPPED FILES 


void * mmap(void *start, size_t length,int prot ,int flags ,int fd,off_t offset); 
int munmap(void *start , size_t length); 
#endif 


The mmap function asks to map | engt hn bytes starting at offset of fset from the file (or other object) specified by fd into 
memory, preferably at address st art . This latter address is ahint only, and is usually specified aso. The actual place where 
the object is mapped is returned by mmap.T he prot argument describes the desired memory protection. It has the following 
bits: 


PROT_EXEC Pages may be executed. 
PROT_READ Pages may be read. 
PROT_WRITE Pages may be written. 


Theflags parameter specifies the type of the mapped object, mapping options, and whether modifications made to the 
mapped copy of the page are private to the process or areto be shared with other references. It has the following bits: 


MAP_FIXED Do not select a different address than the one specified. If the specified address cannot be 
used, mmap will fail. If wap_FIXeED is specified, st art must be a multiple of the pagesize U se of 
this option is discouraged. 

MAP_SHARED Share this mapping with all other processes that map this object. 

MAP_PRIVATE Create a private copy-on-write mapping. 


T hese three flags are described in PO SIX.4. Linux also knows about MAP_DENYWRITE, MAP_EXECUTABLE, and MAP_ANON(YMOUS). 


The munmap system call deletes the mappings for the specified address range and causes further references to addresses within 
the range to generate invalid memory references. 


RETURN VALUE 


On success, mnap returns a pointer to the mapped area. On error, MAP_FAILED (-1) isreturned and errno is set appropriately. 
On SUCCESS, munmap returns @, and on failure it returns -1 and sets errno (probably to EINVAL). 





ERRORS 
EBADF fd isnot a valid file descriptor (and map_ANONYMoUS was not set). 
EACCES MAP_PRIVATE Was asked, but fd is not open for reading. Or MAP_SHARED was asked and 
PROT_WRITE iS set, fd isnot open for writing. 
EINVAL start OFlength, and offset aretoo large, or not aligned on aPaGesize boundary. 
ETXTBUSY MAP_DENYWRITE was set but the object specified by td is open for writing. 
EAGAIN The file has been locked, or too much memory has been locked. 
ENOMEM No memory is available 
CONFORMS TO 


POSIX.4. 
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SEE ALSO 
getpagesize(2), msync(2), shm_open(2), B. O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129, 389-391. 
Linux 1.3.86, 12 April 1996 


modify ldt 


modify_1dt— Gets or sets 1dt 


SYNOPSIS 


#include <linux/ldt.h> #include <linux/unistd.h> 
_syscall3( int, modify_ldt, int, func, void *, ptr, unsigned long, bytecount ) 


int modify_ldt(int func,void *ptr, unsigned long bytecount ); 


DESCRIPTION 


modify_1dt reads or writes the local descriptor table (1at) for a process. T he 1dt is a per-process memory-management table 
used by the i386 processor. For more information on thistable, see an Intel 386 processor handbook. 


When func iS0, modify_1dt reads the 1dt into the memory pointed to by ptr. Thenumber of bytes read is the smaller of 
bytecount and the actual size of the 1dt. 


When func iS 1, modify_1dt modifies one iat entry. ptr points to amodify_idt_Idt_s structure and bytecount must equal the 
size of this structure 


RETURN VALUE 


On Success, modify_1dt returns either the actual number of bytes read (for reading) or a (for writing). On failure, modify_1dt 
returns -1 and sets errno. 


ERRORS 
ENOSYS func isnather @ nor 1. 
EINVAL ptr iS, OF func iS1 and bytecount iS not equal to the size of the structure 
modify_ldt_ldt_s,Orfunc iS1 and thenew iat entry has illegal values. 
EFAULT ptr points outside the address space. 
SEE ALSO 
vmg6(2) 
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get_kernel syms, create module, init_module, delete module 


get_kernel_syms, create_module, init_module, delete_module— Loadable module support 


SYNOPSIS 


#include <linux/module.h> 
int get_kernel_syms(struct kernel_sym *table); 


int create_module(char *module_name, unsigned long size); 


g&t_kernd_syms, create module init_module ddeée module 


int init_module(char *module_name, char *code, unsigned codesize, 
struct mod_routines *routines, struct symbol table *symtab) ; 


int delete_module(char *module_name) ; 


struct kernel_sym { 
unsigned long value; 
char name[SYM_MAX_NAME]; 
}; 


struct mod_routines { 
int (*init) (void); 
void (*cleanup) (void) ; 
}; 


struct module_ref { 
struct module *module; 
struct module_ref *next; 
hs 


struct internal_symbol { 
void *addr; 
char *name; 

}; 


struct symbol_table { 
int size; /* total, including string table!!! */ 
int n_symbols; 
int n_refs; 
struct internal_symbol symbol[Q]; 
struct module_ref ref[0]; 
}; 


DESCRIPTION 


T hese system calls have not yet been included in any library, which means that they have to be called by the 
syscall(_NR_function) mechanism. get_kernel_syms(table); has two uses: First, if table iSNULL, this call will only return the 
number of symbols, including module names, that are available. T his number should be used to reserve memory for that 
many items of struct kernel sym. 


If table isnot NULL, this call will copy all kernel symbols and module names (and version info) from the kernel to the space 
pointed to by table. The entries are ordered in module LIFO order. For each module an entry that describes the module will 
be followed by entries describing the symbols exported by this module. 


N ote that for symbols that describe a module, the value part of the structure will contain the kerne1 address of the structure 
that describes the module 


The name part of the structure is the module name prepended with #, aSin #my module. The symbol that describes a module 
will appear before the symbols defined by this module 


Ahead of the kernel resident symbols, a module name symbol with the “dummy” name¢ will appear. T his information can 
be used to build a table of module references when modules are stacked (or layered). create_module(module_name, size); will 
allocate size bytes of kernel space for a module and also create the necessary kernel structures— called name— for the new 
module The module will now exist in kernel space, with the status MoD_UNINITIALIZED.init module(module_name, code, 
codesize, routines, symtab);. 


Thisis the actual “module loader” that will load the module named name into the kernd. The parameters code and codesize 


refer to the relocated binary object module that is codesize bytes long. N ote that the first 4 bytes will be used as a reference 
counter in kernd space, updated by the mop_INc_USE_COUNT and MOD_DEC_USE_COUNT macros. 
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The functions described in routines will be used to start and stop the module. T hese pointers should therefore contain the 
addresses of the init_module() and cleanup_module() functions that have to be defined for all loadable modules. 


If amodule wants to export symbols for use by other modules, or if the module makes references to symbols defined by other 
modules, the parameter symtab has to point to a structure that describes these. A NULL value for symtab means that no symbols 
are exported and no references to other modules are made. 


The symtab that will be copied into the kernel consists of a symbol table structure immediately followed by astring table, 
containing thenames of the symbols defined by the module T he size element has to include the size of this string table as 
wall. Special considerations follow. 


The n_symbols and n_refs eements tells how many symbols and how many module references are included in the symbol 
table structure. Immediately after these integers, the array of symbol definitions follows. Thename element in each struct 
internal symbol should actually not be an ordinary pointer, but instead the offset of the corresponding string table entry 
relative to the start of the symbol table structure. 


When all defined symbols have been listed, the symbo1_table structure continues with the array of module references, as 
described by the struct module_ref Aenents. Only the module fidd of these structures have to be initialized. The module 
addresses that were obtained from a previous get_kernel_syms Call, for dements with names starting with # should be copied 
to this fidd. 


If the module could be successfully loaded, and if the call to the module function init_module() also succeeds, the status of 
the module will be changed to mop_runnine. Otherwise, the kernel memory occupied by module will be freed. 


delete module (module name); Should be used to unload a module. If the module reference count shows that the module is not 
active, and if there are no references to this module from other modules, the module function cleanup_module() will be 
called. If all these steps succeed, the kernd memory occupied by the module and its structures will be freed. 


DIAGNOSTICS 


If there are any errors, these functions will return the value -1, and the global variable errno will contain the error number. A 
descriptive text will also be written on the console device 


SEE ALSO 


insmod(1), rmmod(1), 1smod(1), ksyms(1) 


HISTORY 


The module support was first conceived by Anonymous. 





Linux version by Bas Laarhoven (bas@vimec.n1), 0.99.14 version by Jon Tombs (jon@gtex@2.us.es), extended by Bjorn 
Ekwall (bjorn@blox.se). 


BUGS 


N aah... 
Linux, 25 January 1995 


mount, umount 


mount, umount— M ount and unmount filesystems. 


SYNOPSIS 


#include <sys/mount.h> 
#include <linux/fs.h> 


int mount(const char *specialfile, const char * dir , 
const char * filesystemtype, unsigned long rwflag , const void * data); 
int umount(const char *specialfile); 


int umount(const char *dir); 


mount, umount 
DESCRIPTION 


mount attaches the filesystem specified by speci al file (which is often a device name) to the directory specified by dir. 
umount removes the attachment of the filesystem specified by specialfile Ordir. 
Only the superuser may mount and unmount filesystems. 


Thetilesystemtype argument may take one of the values listed in /proc/filesystems (SuCh aSminix, ext2, msdos, proc, nfs, 
iso9660). 


Therwflag argument has the magic number oxceen in the top 16 bits, and various mount flags (as defined in <linux/fs.h>) in 
the low order 16 bits: 


#define MS_RDONLY 1 /* mount read-only */ 

#define MS_NOSUID 2 /* ignore suid and sgid bits */ 

#define MS_NODEV 4 /* disallow access to device special files */ 
#define MS_NOEXEC 8 /* disallow program execution */ 

#define MS_SYNC 16 /* writes are synced at once */ 

#define MS_REMOUNT 32 /* alter flags of a mounted FS */ 

#define MS_MGC_VAL OxCOQEDO000 


If the magic number is absent, then the last two arguments are not used. 
Thedata argument is interpreted by the different filesystems. 


RETURN VALUE 


On success, a isreturned. On error, -1 iSreturned and errno isset appropriately. 


ERRORS 


The following error values result from filesystem type independent errors. Each filesystem type may have its own special 
errors and its own special behavior. See the kernd source code for details. 


EPERM The user isnot the superuser. 

ENODEV filesystemtype not configured in thekernd. 

ENOTBLK specialfile isnot ablock device (if a device was required). 

EBUSY special file iS already mounted. Or it cannot be renounted read-only because it still holds 


files open for writing. Or, it cannot be mounted on dir because dir isstill busy (itis the 
working directory of some task, the mount point of another device, has open files, and so 


on). 

EINVAL special file had an invalid superblock. Or, arenount was attempted, whilespecial file 
was not already mounted on dir. Or, an umount was attempted, while dir wasnot a mount 
point. 

EFAULT One of the pointer arguments points outside the user address space. 

ENOMEM Thekernel could not allocate a free page to copy filenames or data into. 

ENAMETOOLONG A pathname was longer than maXPATHLEN. 

ENOENT A pathname was empty or had anonexistent component. 

ENOTDIR Thesecond argument, or a prefix of the first argument, is not a directory. 

EACCES A component of a path was not searchable 


Or, mounting a read-only filesysten was attempted without giving thems_rbon_y flag. 
Or, the block devicespeci alfile iSlocated on a filesystem mounted with the ms_NoDEV 
option. 

ENXIO The major number of the block devices pecialfile is out of range 

EMFILE (In case no block deviceis required:) T able of dummy devices is full. 
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CONFORMS TO 


T hese functions are rather Linux specific. 


SEE ALSO 


mount(8), umount(8) 
Linux 1.1.67, 28 N ovenber 1994 


mprotect 


mprotect— Controls allowable accesses to a region of manory 


SYNOPSIS 


#include <sys/mman.h> 
int mprotect(caddr_t addr, size_t *len, int prot); 


DESCRIPTION 


mprotect controls how a section of memory can be accessed. | f an access is disallowed by the protection given it, the program 
receives a SIGSEGV. 


prot isabitwiseO R of the following values: 


PROT_NONE The memory cannot be accessed at all. 
PROT_READ The memory can be read. 

PROT_WRITE Thememory can bewritten to. 
PROT_EXEC Thememory can contain executing code 


The new protection replaces any existing protection. For example, if the memory had previously been marked prot_READ, and 
morotect iSthen called with prot PROT_wRITE, it will no longer be readable 


RETURN VALUE 
On success, mprotect returns 0. On error, -1 is returned and errno is set appropriately. 
ERRORS 
EINVAL addr isnot a valid pointer. 
EFAULT The memory cannot be accessed. 
EACCES Thememory cannot be given the specified access. T his can happen, for example if you 
mmap(2) a file to which you have read-only access, then ask mprotect to mark it PROT_WRITE. 
ENOMEM Internal kernel structures could not be allocated. 
EXAMPLE 


#include <stdio.h> 
#include <stdlib.h> 
#include <errno.h> 
#include <sys/mman.h> 


int 
main(void) 
{ 
char *p; 
char c; 


/* Allocate a buffer; it will have the default 
protection of PROT_READ|PROT WRITE. */ 

p = malloc(1024); 

if (1p) { 
perror("Couldn't malloc (1024)"); 
exit(errno); 


} 
c = p[666]; /* Read; ok */ 
p[666] = 42; /* Write; ok */ 


/* Mark the buffer read-only. */ 

if (mprotect(p, 1024, PROT_READ)) { 
perror("Couldn't mprotect"); 
exit(errno); 


} 

c = p[666]; /* Read; ok */ 

p[666] = 42; /* Write; program dies on SIGSEGV */ 
exit(0); 


SEE ALSO 
mmap(2) 
Linux 1.2, 23 June1995 


mremap 


mremap— Ranapsa virtual memory address 


SYNOPSIS 


#include <unistd.h> 
#include <sys/mman.h> 
void * mremap(void * old_address, size_t old_size , size_t new_size, unsigned long flags) 


DESCRIPTION 


mremap expands (or shrinks) an existing memory mapping, potentially moving it at the same time (controlled by thet! ags 
argument and the available virtual address space). 


old_address iStheold address of the virtual memory block that you want to expand (or shrink). N otethat ol d_address hasto 
be page aligned. o! d_size istheold size of the virtual memory block. new_size is the requested size of the virtual memory 
block after the resize. 


Thefl ags argument is a bitmap of flags. 


In Linux the memory is divided into pages. A user process has one or linear virtual memory segments. Each virtual memory 
segment has one or more mappings to real memory pages (in the page table). Each virtual memory segment has its own 
protection (access rights), which may cause a segmentation violation if the memory is accessed incorrectly (for example, 
writing to aread-only segment). Accessing virtual memory outside of the segments will also cause a segmentation violation. 


mremap uses the Linux page table scheme. mremap changes the mapping between virtual addresses and memory pages. T his can 
be used to implenent a very efficient realloc. 
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FLAGS 
MREMAP_MAYMOVE Indicates whether the operation should fail, or changes the virtual address if the resize 
cannot be done at the current virtual address. 
RETURN VALUE 
On SUCCESS, mremap returns a pointer to the new virtual memory area. On error, -1 is returned, and errno is set appropriately. 
ERRORS 

EINVAL An invalid argument was given. M ost likely ol d_address was not page aligned. 

EFAULT Segmentation fault. Some address in the range old_address toold_address+old size isan 
invalid virtual memory address for this process. You can also get EFAULT even if there exist 
mappings that cover the whole address space requested, but those mappings are of different 
types. 

EAGAIN Thememory segment is locked and cannot be remapped. 

ENOMEM The memory area cannot be expanded at the current virtual address, and the mrEMAP_MAY MOVE 
flag isnot set in flags. Or thereis not enough (virtual) memory available. 

SEE ALSO 


getpagesize(2), realloc(3), malloc(3), brk(2), sbrk(2), mmap(2), your favorite O S text book for moreinformation on paged 
memory. (M odern O perating Systemsby Andrew S. T annenbaum, | nside Linux by Randolf Bentson, T he D esgn of the U NIX 
Operating Sytem by M aurice}. Bach.) 


Linux 1.3.87, 12 April 1996 


msgctl 


msgct1— H andles message control operations 


SYNOPSIS 


# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int msgctl ( int msgid, int cmd , struct msqid_ds *buf ); 
int cmd, struct msqid_ds *buf; 


DESCRIPTION 

The function performs the control operation specified by cmd on the message queue with identifier ms qi d. Legal values for cmd 

are 

IPC_STAT Copies info from the message queue data structureinto the structure pointed to by buf. The 
user must have read access privileges on the message queue. 

IPC_SET W rites the values of some menbers of the msqid ds structure pointed to by buf to the 
message queue data structure, updating also itsmsg_ctime manber. Considered menbers 
from the user-supplied struct msqid ds pointed to by buf arémsg_perm.uid, msg_perm.gid, 
and msg_perm.mode /* only lowest 9-bits */ msg qbytes. 

The calling process effective user |D must be one among superuser, creator or owner of the 
message queue. O nly the superuser can raise the msg_qbytes value beyond the systen 
parameter MSGMNB. 

IPC_RMID Remove immediately the message queue and its data structures awakening all waiting reader 


and writer processes (with an error return and errno set to Erprm). The calling process 
effective user 1D must be one among superuser, creator or owner of the message queue. 
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RETURN VALUE 
If successful, the return value will be o;otherwise, the return value will be -1 with errno indicating the error. 
ERRORS 
For a failing return, errno will be set to one of the following values: 
EACCESS The argument cmd is equal to 1Pc_sTaT, but the calling process has no read access permis- 
sions on the message queue msqid. 
EFAULT The argument cmd has value 1pc_seT or 1Pc_sTAT, but the address pointed to by buf isn’t 
accessible. 
EIDRM T he message queue was removed. 
EINVAL Invalid value for cmd Or msqid. 
EPERM The argument cmd has value 1Pc_seT or IPc_RMID, but the calling process effective user | D 


has insufficient privileges to execute the command. N ote that this is also the case of a 
nonsuperuser process trying to increase the msg_qbytes value beyond the value specified by 
the system parameter MsGMnB. 


NOTES 


The IPC_INFO, MSG_STAT, and msG_INFO control calls are used by the ipcs(1) program to provide information on allocated 
resources. In the future these can be modified as needed or moved to a proc file system interface 


SEE ALSO 
ipce(5), msgget(2), msgsnd(2), msgrcv(2) 
Linux 0.99.13, 1 November 1993 


msgget 


msgget— Gets a message queue identifier 


SYNOPSIS 


# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int msgget ( key_t key,int msgflg ); 


DESCRIPTION 


The function returns the message queue identifier associated to the value of thekey argument. A new message queue is 
created if key has value 1PC_PRIVATE Or key isn’t IPC_PRIVATE, NO existing message queue is associated to key, and IPC_CREAT iS. 
asserted in ms gf! (that is, msgflg &IPC_CREAT isn’t a). The presence in ms gf ig of the fidds 1pc_creat and 1Pc_ExXcL plays the 
same role, with respect to the existence of the message queue, as the presence of o_creaT and o_excL in the mode argument of 
the op_en(2) system call: That is, the msgget function fails if ms gf 1g asserts both 1pc_cREAT and rpc_EXxcL and a message queue 
already exists for key. 


Upon creation, the lower 9 bits of the argument ms gf! 9 define the access permissions (for owney, group, and others) to the 
message queue in the same format, and with the same meaning, as for the access permissions parameter in the open(2) or 
creat(2) system calls (though the execute permissions are not used by the system). 

Furthermore, while creating, the system call initializes the systan message queue data structure msqid ds as follows: 
msg_perm.cuid and msg_perm.uid are set to the effective user ID of the calling process. 

msg_perm.cgid and msg_perm.gid are set to the effective group |D of the calling process. 
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808 
The lowest-order 9 bits of msg_perm.mode are set to the lowest-order 9 bit of ms gf 1g. 
msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime are set to 0. 
msg_ctime iS set to the current time 
msg_qbytes is set to the system limit msGnne. 
If the message queue already exists, the access permissions are verified, and a check is made to see whether it is marked for 
destruction. 
RETURN VALUE 
If successful, the return value will be the message queue identifier (a positive integer), otherwise -1 with errno indicating the 
error. 
ERRORS 
For a failing return, errno will be set to one of the following values: 
EACCES A message queue exists for key , but the calling process has no access permissionsto the 
queue. 
EEXIST A message queue exists for key and ms gf! was asserting both 1pc_cREAT and IPC_EXCL. 
EIDRM The message queue is marked asto be removed. 
ENOENT N o message queue exists for key and msgf!g wasn’t asserting IPC_CREAT. 
ENOMEM A message queue has to be created but the systen has not enough memory for the new data 
structure, 
ENOSPC A message queue has to be created but the systen limit for the maximum number of 
message queues (uscMnt) would be exceeded. 
NOTES 


IPC_PRIVATE isn't a flag fidd, but a key_t type. If this special value is used for key, the system call ignores everything but the 
lowest-order 9 bits of msgfig and creates a new message queue (on success). 


The following is a system limit on message queue resources affecting amsgget Call: 
MSGMNI Systemwide maximum number of message queues; policy dependent. 


BUGS 


Use of 1pc_PRIVATE doesn’t inhibit other processes the access to the allocated message queue. 


Asfor thefiles, there is currently no intrinsic way for a process to ensure exclusive access to a message queue. Asserting both 
IPC_CREAT and IPC_EXCL iN msgf!g only ensures (on success) that a new message queue will be created; it doesn’t imply 
exclusive access to the message queue. 


SEE ALSO 


ftok(3), ipc(5), msgct1(2), msgsnd(2), msgrcev(2) 
Linux 0.99.13, 1 November 1993 


msgop 


msgop— C ompletes message operations 


SYNOPSIS 


# include <sys/types.h> 
# include <sys/ipc.h> 
# include <sys/msg.h> 
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int msgsnd ( int msgid, struct msgbuf *msgp" ,int msgsz,int msgflg ); 


int msgrcv ( int msgid, struct msgbuf *msgp,int msgsz,long msgtyp,int msgflg ); 


DESCRIPTION 
To send or receive a message, the calling process allocates a structure that looks like the following: 
struct msgbuf { 
long mtype; /* message type, must be > O */ 
char mtext[1]; /* message data */ 
}; 
but with an array mtext of size ms gsz, a nonnegative integer value. The structure member mtype must have a strictly positive 
integer value that can be used by the receiving process for message sdection (see the section about msgrcv). 


The calling process must have write access permissions to send and read access permissions to receive a message on the queue. 


The msgsnd system call queues a copy of the message pointed to by thems gp argument on the message queue whose identifier 
is specified by the value of the ms qi d argument. 


The argument ms gf! 9 specifies the system call behavior if queuing the new message will require more than msg_qbytes in the 
queue. Asserting 1Pc_nowart, the message will not be sent and the system call fails, returning with errno set to EAGAIN. 

O therwise the process is suspended until the condition for the suspension no longer exists (in which case the message is sent 
and the system call succeeds), or the queue is renoved (in which case the system call fails with errno set to ErpRM), or the 
process receives a signal that has to be caught (in which case the system call fails with errno set to EINTR). 


Upon successful completion, the message queue data structure is updated as follows: 


msg_lspid Set to the process D of the calling process. 
msg_qnum Incremented by 1. 
msg_stime Se to the current time. 


The system call msgrev reads a message from the message queue specified by msgid into the msgbuf pointed to by thems gp 
argument, renoving from the queue, on success, the read message. 

The argument ms gsz specifies the maximum size in bytes for the member mtext of the structure pointed to by the ms gp 
argument. If the message text has length greater than msgsz, then if themsgf!g argument asserts msG_NoERROR, the message text 
will be truncated (and the truncated part will be lost); otherwise, the message isn’t removed from the queue and the system 
call fails, returning with errno set to E2BIG. 

The argument ms gt yp specifies the type of message requested as follows: 


If msgtyp iSo, the message on the queue’s front is read. 


If msgtyp iS greater than a, the first message on the queue of typemsgt yp iS read if msa_ExcEPT isn’t asserted by thems gf! g 
argument; otherwise, the first message on the queue of type not equal to msgtyp will be read. 


If msgtyp iSless than o, the first message on the queue with the lowest type less than or equal to the absolute value of ms gt yp 
will be read. 


The ms gf! 9 argument asserts none, one, or more (O R-ing than) among the following flags: 


IPC_NOWAIT For immediate return if no message of the requested type is on the queue. The system call 
fails with errno set to ENomsG. 
MSG_EXCEPT Used with msgt yp greater than a to read the first message on the queue with message type 


that differs from ms gt yp. 
MSG_NOERROR To truncate the message text if longer than ms gsz bytes. 
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If no message of the requested type is available and rpc_nowarT isn’t asserted in ms gf! g, the calling process is blocked until one 
of the following conditions occurs: 


A message of the desired type is placed on the queue 
The message queue is removed from the system. In such a case the system call fails with errno set to EIDRM. 
The calling process receives a signal that has to be caught. In such a case the system call fails with errno set to EINTR. 


Upon successful completion, the message queue data structure is updated as follows: 


msg_Irpid Set to the process D of the calling process. 
msg_qnum Decrenented by 1. 
msg_rtime Set to the current time. 

RETURN VALUE 


On afailure, both functions return -1 with errno indicating the error; otherwise, msgsnd returns 0 and msgrve returns the 
number of bytes actually copied into the mtext array. 


ERRORS 


When msgsnd fails, at return errno will be set to one of the following values: 


EAGAIN The message can’t be sent due to the msg_qbytes limit for the queue, and IPc_NowAIT was 
asserted in mgsfig. 

EACCES The calling process has no write access permissions on the message queue. 

EFAULT The address pointed to by ms gp isn’t accessible 

EIDRM T he message queue was removed. 

EINTR Sleeping on a full message queue condition, the process recd ved a signal that had to be 
caught. 

EINVAL Invalid msgid value, or nonpositive mt ype value, or invalid ms gsz value (less than @ or greater 
than the system value MsemAx). 

ENOMEM The systen has not enough memory to make a copy of the supplied msgbuf. 


When nsgrcv fails, at return errno will be set to one of the following values: 


E2BIG The message text length is greater than ms gsz and MsG_NoERROR isn’t asserted in ms gf! g. 

EACCES The calling process has no read access permissions on the message queue. 

EFAULT T headdress pointed to by ms gp isn’t accessible 

EIDRM W hile the process was sleeping to receive a message, the message queue was renoved. 

EINTR W hile the process was sleeping to receive a message, the process received a signal that had to 
be caught. 

EINVAL Illegal ms gqid value, or msgsz less than @. 

ENOMSG IPC_NOWAIT was asserted in ms gf! g and no message of the requested type existed on the 
message queue 

NOTES 

The followings are system limits affecting amsgsnd system call: 

MSGMAX M aximum size for a message text; the implementation set this value to 4080 bytes. 

MSGMNB D efault maximum size in bytes of a message queue: policy dependent. The superuser can 


increase the size of a message queue beyond mscmnB by amsgct1 system call. 


The implementation has no intrinsic limits for the systenwide maximum number of message headers (usctaL) and for the 
systemwide maximum size in bytes of the message pool (wscPooL). 
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SEE ALSO 


ipce(5), msgct1(2), msgget(2), msgrcv(2), msgsnd(2) 


msync 


msync— Synchronizes a file with a memory map 


SYNOPSIS 


#include <unistd.h> 
#include <sys/mman.h> 


#ifdef_POSIX_MAPPED_FILES 
#ifdef_POSIX_SYNCHRONIZED_I0 


int msync(const void *start, size_t length,int flags); 
#endif 
#endif 


DESCRIPTION 


msync flushes changes made to the in-core copy of a file that was mapped into memory using mmap(2) back to disk. Without 
use of this call, there is no guarantee that changes are written back before munmap(2) is called. To be more precise, the part of 
the file that corresponds to the memory area starting at start and having length | ength is updated. Theflags argument may 
have the bits ms_ASYNC, MS_SYNC, aNd MS_INVALIDATE set, but not both ms_async and ms_SyYNc. mS_ASYNC Specifies that an update 
be scheduled, but the call returns immediately. ws_sync asks for an update and waits for it to complete. ms_INVALIDATE asks to 
invalidate other mappings of the same file (so that they can be updated with the fresh values just written). 


RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned and errno isset appropriately. 
ERRORS 
EINVAL start isnot amultiple of paces1ze, or any bit other than ms_ASYNC | MS_INVALIDATE ! 
MS_SYNC iSSetinflags. 
EFAULT Theindicated memory (or part of it) was not mapped. 
CONFORMS TO 
POSIX.4. 
SEE ALSO 


mmap(2), B.O. Gallmeister, PO SIX.4, O'Reilly, pp. 128-129, 389-391. 
Linux 1.3.86, 12 April 1996 
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munlock— Reenables paging for some parts of memory 


SYNOPSIS 


#include <sys/mman.h> 
int munlock(const void *addr, size t len); 
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DESCRIPTION 


munlock remables paging for the memory in the range starting at addr with length | en bytes. All pages that contain a part of 
the specified memory range can after calling munlock be moved to external swap space again by the kernd. 


M emory locks do not stack, that is, pages that have been locked several times by calls to mlock Or mlockal1 will be unlocked 
by asingle call to munlock for the corresponding range or by munlockall. Pages that are mapped to several locations or by 
several processes stay locked into RAM as long as they are locked at least at one location or by at least one process. 


On POSIX systems on which mlock and munlock are available _POSIX_MEMLOCK_RANGE is defined in <unistd.h> 
and the value pacesize from <limits.h> indicates the number of bytes per page. 
RETURN VALUE 


On success, munlock returns 0. On error, -1 isreturned, errno is set appropriately, and no changes are made to any locksin 
the address space of the process. 


ERRORS 
ENOMEM Some of the specified address range does not correspond to mapped pages in the address 
space of the process. 
EINVAL len WaSnot a positive number. 
STANDARDS 
POSIX.1b, SVR4 
SEE ALSO 


mlock(2), mlockal1(2), munlockal1(2). 
Linux 1.3.43, 26 November 1995 


munlockall 
munlockall— Regables paging for calling process 


SYNOPSIS 


#include <sys/mman.h> 
int munlockall(void) ; 


DESCRIPTION 
munlockall reenables paging for all pages mapped into the address space of the calling process. 


Memory locks do not stack, that is, pages that have been locked several times by calls to mlock Or mlocka11 will be unlocked 
by asingle call to munlocka11. Pages that are mapped to several locations or by several processes stay locked into RAM as long 
as they are locked at least at one location or by at least one process. 


On POSIX systems on which mlockall and munlockall are available, pos1x_memLock iSdefined in <unistd.h>. 


RETURN VALUE 


On SUCCess, munlockall returns 0. On error, -1 is returned and errno is set appropriately. 


STANDARDS 
POSIX.1b, SVR4 


nanos eeo 


Linux 1.3.43, 26 Novenber 1995 


SEE ALSO 


mlockall(2), mlock(2), munlock(2) 


nanosleep 


nanosleep— Pauses execution for a specified time 


SYNOPSIS 


#include <time.h> 
int nanosleep(const struct timespec *req, struct timespec *rem); 


DESCRIPTION 


nanosleep Celays the execution of the program for at least the time specified in *req.T he function can return earlier if a signal 
has been delivered to the process. In this case it returns -1, sets errno to EINTR, and writes the remaining timeinto the 
structure pointed to by rem unlessrem iS NULL. The value of *rem can then be used to call nanosleep again and complete the 
specified pause. 


The structure ti mespec is used to specify intervals of time with nanosecond precision. It is specified in <ti me. h> and hasthe 
form 


struct timespec 

{ 

time_t tv_sec; /* seconds */ 
long tv_nsec; /* nanoseconds */ 
}; 


The value of thenanoseconds fidd must bein the range 0 to 999 999 999. 


Compared to sleep(3) and usleep(3), nanosleep has the advantage of not affecting any signals; it is standardized by POSIX, it 
provides higher timing resolution, and it allows to continue a Sleep that hasbem interrupted by asignal more easily. 


ERRORS 
In case of an error or exception, the nanosleep system call returns -1 instead of @ and sets errno to one of the following values: 
EINTR T he pause has been interrupted by a nonblocked signal that was ddivered to the process. 
The remaining sleep time has been written into «rem so that the process can easily call 
nanosleep again and continue with the pause. 
EINVAL The valuein thetv_nsec fidd was not in the range 0 to 999 999 999 ortv_sec was negative 
BUGS 


The current implementation of nanosleep is based on the normal kernd timer mechanism, which has a resolution of 1/HZ s 
(that is, 1Oms on Linux/i386 and Imson Linux/Alpha). Therefore, nanosleep pauses always for at least the specified time 
however, it can take up to 10ms longer than specified until the process becomes runnable again. For the same reason, the 
value returned in case of a delivered signal in *r em is usually rounded to the next larger multiple of 1/H Z s. 


Because some applications require much more precise pauses (for example, in order to control some time-critical hardware), 

nanosleep iS also capable of short high-precision pauses. If the process is scheduled under a real-time policy such as 

SCHED_FIFO Or SCHED_RR, then pauses of up to 2mswill be performed as busy waits with microsecond precision. 
STANDARDS 

POSIX.1b 
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SEE ALSO 


sleep(3), usleep(3), sched_setscheduler(2), timer_create(2) 
Linux 1.3.85, 10 April 1996 


nice 
nice— Changes process priority 


SYNOPSIS 


#include <unistd.h> 
int nice(int inc); 


DESCRIPTION 
nice addsi nc to the priority for the calling PID . N ote that only the superuser may specify a negative increment, or priority 
increase. N ote that internally, a higher number is a higher priority. Do not confusethis with the priority scheme as used by 
the nice interface. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isse@t appropriately. 
ERRORS 
EPERM A nonsuperuser attempts to do a priority increase. anumerical decrease, by supplying a 
negativeinc. 
CONFORMS TO 
SVID EXT, AT&T, X/OPEN, BSD 4.3 
SEE ALSO 


nice(1), setpriority(2), fork(2), renice(8) 
Linux, 28 M arch 1992 


oldfstat, oldlstat, oldstat, oldolduname, olduname 


oldfstat, oldlstat, oldstat, oldolduname, olduname— O bsolete system calls 


SYNOPSIS 
O bsolete system calls. 


DESCRIPTION 


The Linux 1.3.6 kernel implements these calls to support old executables. T hese calls return structures that have grown since 
their first implementations, but old executables must continue to receive old smaller structures. 


Current executables should be linked with current libraries and never use these calls. 


SEE ALSO 


fstat(2), 1stat(2), stat(2), uname(2), undocumented(2), unimplemented(2) 
Linux 1.3.6, 22 July 1995 
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open, creat 


open, creat— O pen and possibly create a file or device 


SYNOPSIS 


#include <sys/types.h> 

#include <sys/stat.h> 

#include <fcntl.h> 

int open(const char *pathname,int flags); 

int open(const char *pathname,int flags ,mode_t mode); 
int creat(const char *pathname,mode t mode); 


DESCRIPTION 
open attempts to open afile and return a file descriptor (a small, nonnegative integer for usein read, write, and so on). 
flags iS One Of 0_RDONLY, 0 WRONLY, Or O_RDWR, which request opening the file read-only, write-only, or read/write, respectively. 
flags may also be bitwise ored with one or more of the following: 


0_CREAT If the file does not exist it will be created. 

0_EXCL W hen used with o_crear, if thefile already exists, it isan error and the open will fail. Seethe 
“Bugs” section, though. 

O_NOCTTY If pathname refers to aterminal device— see tty(4)— it will not become the process's 
controlling terminal even if the process does not have one 

0_TRUNC If the file already exists, it will be truncated. 

0_APPEND The file is opened in append mode. Initially, and before each write, thefile pointer is 
positioned at the end of thefile as if with 1seek. 

0_NONBLOCK OF 0_NDELAY Thefile is opened in nonblocking mode N either the open nor any subsequent operations on 
the file descriptor that is returned will cause the calling process to wait. 

0_SYNC The file is opened for synchronous I/O. Any writes on the resulting file descriptor will 





block the calling process until the data has been physically written to the underlying 
hardware. See the “Bugs” section, though. 


Some of these optional flags can be altered using fent1 after the file has been opened. 


mode specifies the permissions to use if anew file is created. It is modified by the process's umask in the usual way: The 
permission of the created file is (mode & ~umask). 


The following symbolic constants are provided for mode: 


S_IRWXU 00700 user (file owner) has read, write, and execute permission. 
S$ _IRUSR (S_IREAD) 00400 user has read permission. 

S$ _IwusR (S_IWRITE) 00200 user has write permission. 

S$ _IXUSR (S_IEXEC) 00100 user has execute permission. 

S_IRWXG 00070 group has read, write, and execute permission. 
S_IRGRP 00040 group has read permission. 

S_IWGRP 00020 group has write permission. 

S_IXGRP 00010 group has execute permission. 

S_IRWXO 00007 others have read, write, and execute permission. 
S_IROTH 00004 others have read permission. 

S_IWOTH 00002 others have write permission. 

S_IXOTH 00001 others have execute permission. 


mode Should always be specified when o_creat isin thefiags, and isignored otherwise. 
creat iS equivalent to open with flags equal to 0_CREAT!0_WRONLY!0_TRUNC. 
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RETURN VALUE 


open and creat return the new file descriptor, or -1 if an error occurred (in which case errno is set appropriately). N ote that 
open Can open device-special files, but creat cannot create them— use mknod(2) instead. 











ERRORS 
EEXIST athname already exists and 0_CREAT and 0_EXxcL were used. 
EISDIR athname refersto adirectory and the access requested involved writing. 
ETXTBSY athname refers to an executable image which is currently being executed and write access 
was requested. 
EFAULT athname points outside your accessible address space. 
EACCES The requested access to the file is not allowed, or one of the directories in pathname did not 
allow search (execute) permission. 
ENAMETOOLONG at hname was too long. 
ENOENT A directory component in pat hname does not exist or isa dangling symbolic link. 
ENOTDIR A component used asa directory in pat hname isnot, in fact, a directory. 
EMFILE The process already has the maximum number of files open. 
ENFILE Thelimit on the total number of files open on the system has been reached. 
ENOMEM Insufficient kernel memory was available. 
EROFS pathname réfersto afileon a read-only filesystem and write access was requested. 
ELOOP pat hname Contains a reference to acircular symbolic link, that is, asymbolic link whose 
expansion contains a reference to itself. 
ENOSPG pathname was to be created but the device containing pat hname haSno room for thenew file. 
CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 
BUGS 


0_sync isnot currently implemented (as of Linux 0.99p!7). 
There are many infdicities in the protocol underlying N FS, affecting amongst others 0_syNc, 0_NDELAY, and 0_APPEND. 
0_EXcL is broken on NFS filesystems; programs that rely on it for performing locking tasks will contain a race condition. T he 
solution for performing atomic file locking using alockfile is to create a unique file on the same fs (for example, incorporat- 
ing hostname and PID ), use 1ink(2) to make alink to the lockfile, and use stat(2) on the unique file to check if its link 
count has increased to 2. Do not use the return value of the 1ink() call. 

SEE ALSO 


read(2), write(2), font1(2), close(2), unlink(2), mknod(2), stat(2), umask(2), mount(2), socket(2), socket(2), fopen(3), Link(2) 
Linux 0.99.7, 21 July 1993 


outh, outw, outl, outsb, outsw, outsl 


outb, outw, outl, outsb, outsw, outsl1— Port output 
inb, inw, inl, insb, insw, insl— Port input 


outb_p, outw_p, outl_p, inb_p, inw_p, inl_p— Pausel/O 


DESCRIPTION 


This family of functions is used to do low-level port input and output. T hey are primarily designed for internal kernel use, 
but can be used from user space, given the following information in addition to that given in outb(9). 


personality 817 


You compile with -o or -o2 or something similar. The functions are defined as inline macros and will not be substituted in 
without optimization enabled, causing unresolved references at link time 


Y ou use ioperm(2) or alternatively iop1(2) to tell the kernal to allow the user space application to access the!/O ports in 
question. Failure to do this will cause the application to receive a segmentation fault. 


CONFORMS TO 


outb and friends are hardware specific. The port and value arguments are in the opposite order from most DOS implenenta- 
tions. 


SEE ALSO 
outb(9), ioperm(2), iop1(2) 
Linux, 29 N ovember 1995 


pause 


pause— W aits for signal 


SYNOPSIS 


#include <unistd.h> 
int pause(void) ; 


DESCRIPTION 


The pause systan call causes the invoking process to sleep until a signal is recdved. 


RETURN VALUE 


pause always returns -1, and errno is Set to ERESTARTNOHAND. 


ERRORS 


EINTR Signal was received. 


CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 
kill(2), select(2), signal(2) 
Linux, 31 August 1995 


personality 
personality— Sets the process execution domain 


SYNOPSIS 


int personality(unsigned long persona); 


DESCRIPTION 


Linux supports different execution domains, or personalities, for each process. Among other things, execution domains tell 
Linux how to map signal numbers into signal actions. The execution domain system allows Linux to provide limited support 
for binaries compiled under other UN IX-like operating systems. 


personality will make the execution domain referenced by persona the new execution domain of the current process. 
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RETURN VALUE 


On SUCCESS, persona ismadethenew execution domain and the previouSpersona iSreturned. On error, -1 isreturned and 
errno is set appropriately. 


ERRORS 

EINVAL persona doesnot refer to a valid execution domain. 
FILE 

/usr/include/linux/personality.h 
CONFORMS TO 


personality iS Linux specific. 
Linux 2.0, 22 July 1996 


phys 


phys— Allows a process to access physical addresses (this command is not implemented) 


SYNOPSIS 


int phys(int physnum, char *virtaddr,longsize, char *physaddr) ; 


DESCRIPTION 
W arning: Because this function is not implemented as of Linux 0.99.11, it will always return -1 and set errno to ENosys. 


phys maps arbitrary physical memory into a process's virtual address space. physnum isa number (0-3) that specifies which of 
the four physical spaces to set up. Up to four phys calls can be active at any onetime virtadar is the process's virtual address. 
size isthe number of bytes to map in. physadar is the physical address to map in. 


Valid virtaddr and physaddr values are constrained by hardware and must be at an address multiple of the resolution of the 
CPU's memory management schene. If size is nonzero, size is rounded up to the next MMU resolution boundary. If size is 
0, any previous phys(2) mapping for that physnum is nullified. 


RETURN VALUE 


On success, 0 is returned. On error, -1 is returned and errno is set appropriately. 


CONFORMS TO 
version 7 AT&T UNIX 


BUGS 


phys iS very machine dependent. 


SEE ALSO 


mmap(2), munmap(2) 
Linux 0.99.11, 24 July 1993 


pipe 


pipe— Creates a pipe 


profil 


SYNOPSIS 


#include <unistd.h> 
int pipe(int filedes[2]); 


DESCRIPTION 


pipe creates a pair of file descriptors, pointing to a pipe inode, and places them in the array pointed to by filedes. filedes[0] 
is for reading, filedes[1] isfor writing. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned and errno isset appropriately. 
ERRORS 
EMFILE Too many file descriptors are in use by the process. 
ENFILE The system file table is full. 
EFAULT filedes is not valid. 
SEE ALSO 


read(2), write(2), fork(2), socketpair(2) 
Linux 0.99.11, 23 July 1993 


profil 


profil— Execution time profile 


SYNOPSIS 


#include <unistd.h> 
int profil(char *buf, int bufsiz,int offset ,int scale); 


DESCRIPTION 


Under Linux 0.99.11, profil isnot implemented in the kernd. Instead, the DLL 4.4.1 libraries provide a user-space 
implementation. 


buf points to bufsiz bytesof core Every virtual 10 milliseconds, the user’s program counter (PC) is examined: of fset is 
subtracted and the result is multiplied by scale. If this addressisin but, the word pointed to is incremented. 


If scale iSless than 2 or bufsiz iso, profiling is disabled. 


RETURN VALUE 


a is always returned. 


BUGS 
profil cannot be used on aprogram that also uses ITIMER_PROF itimers. 
Calling profii with an invalid buf will result in acore dump. 
Truekernd profiling provides more accurate results. 


SEE ALSO 
gprof(1), setitimer(2), signal(2), sigaction(2) 
Linux 0.99.11, 23 July 1993 
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ptrace 


ptrace— Process trace 


SYNOPSIS 


#include <sys/ptrace.h> 


int ptrace(int request ,int pid,int addr ,int data); 


DESCRIPTION 


ptrace provides a means by which a parent process can control the execution of a child process and examine and change its 
core image. Its primary useis for the implementation of breakpoint debugging. A traced process runs until asignal occurs. 
Then it stops and the parent is notified with wait(2). W hen the process isin the stopped state, its memory can be read and 
written. T he parent can also cause the child to continue execution, optionally ignoring the signal which caused stopping. 


The value of the request argument determines the precise action of the system call: 


PTRACE_TRACEME 


PTRACE_PEEKTEXT, 
PTRACE_PEEKDATA 


PTRACE_PEEKUSR 


PTRACE_POKETEXT, 
PTRACE_POKEDATA 


PTRACE_POKEUSR 


PTRACE_SYSCALL, 
PTRACE_CONT 


PTRACE_KILL 
PTRACE_SINGLESTEP 
PTRACE_ATTACH 
PTRACE_DETACH 


NOTES 


This process isto be traced by its parent. The parent should be expecting to trace the child. 
Read word at location addr. 


Read word at location addr in the user area. 
Write word at location addr. 


Write word at location addr in the user area. 
Restart after signal. 


Send the child a stek1Lt to make it exit. 

Sé& the trap flag for single stepping. 

Attach to the process specified in pid. 

D etach a process that was previously attached. 


init, the process with process|D 1, may not use this function. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned and errno isset appropriately. 


ERRORS 


EPERM 
ESRCH 
EIO 


CONFORMS TO 


The specified process (that is, init), cannot be traced or is already being traced. 
The specified process does not exist. 
Request is not valid. 


SVID EXT, AT&T, X/OPEN, BSD 4.3 


SEE ALSO 


gdb(1), exec(2), signal(2), wait(2) 


Linux 0.99.11, 23 July 1993 
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quotactl 


quotact1— M anipulates disk quotas 


SYNOPSIS 


#include <sys/types.h> 

#include <sys/quota.h> 

int quotactl (int cmd, const char *special , intid , caddr_t addr); 

#include <linux/unistd.h> 

syscall4(int, quotactl, int, cmd, const char *, special ,int, id, caddr_t, addr); 


DESCRIPTION 


The quota system defines for each user or group a soft limit and a hard limit bounding the amount of disk spacethat can be 
used on a given filesystem. Thehard limit cannot be crossed. T he soft limit can be crossed, but warnings will ensue. 

M oreover, the user cannot be above the soft limit for more than one week (by default) at a time After this week the soft limit 
counts asa hard limit. 


The quotact1 system call manipulates these quotas. Its first argument is of the form 

QCMD (subemd, type) 

where type is ether usrauoTa or GRPQUOTA (for user quota and group quota, respectively. 
Thesecond argument special is the block special device these quotas apply to. It must be mounted. 
The third argument ID isthe user or group ID these quotas apply to (when relevant). 

The fourth argument, addr, is the address of a data structure, deoending on the command. 





The subemd is one of the following: 
Q_QUOTAON Enables quotas. Theaddr argument is the pathname of the file containing the quotas for the filesystem. 
Q_QUOTAOFF Disables quotas. 
Q_GETQUOTA Gets limits and current usage of disk space. The addr argument is a pointer to adqb1k structure 
(defined in <sys/quota.h>). 
Q_SETQUOTA Sets limits and current usage; addr is as before 
Q_SETQLIM Sets limits; addr is as before. 
Q_SETUSE Sets usage. 
Q_SYNC Syncs disk copy of a filesystem’s quotas. 
Q_GETSTATS Gets collected stats. 
RETURN VALUE 
On success, quotact1 returns @. On error, -1 is returned and errno is set appropriately. 
ERRORS 
ENOPKG Thekernel was compiled without quota support. 
EFAULT Bad addr value. 
EINVAL type isnot aknown quota type Or special could not be found. 
ENOTBLK special isnot ablock special device 
ENODEV special cannot befound in the mount table 
EACCES The quota file is not an ordinary file 
EIO Cannot read or write the quota file 


EMFILE Too many open files: Cannot open quota file 
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EBUSY Q_QUOTAON was asked, but quota were enabled already. 
ESRCH Q _GETQUOTA OF Q_SETQUOTA OF Q_SETUSE OF Q_SETQLIM Was asked for a filesystem that didn’t have quota 
enabled. 
EPERM T he process was not root (for the filesystan), and @_GETauoTA was asked for another ID than that of the 
process itself, or anything other than @_GETSTATS OF @_SYNC Was asked. 
CONFORMS TO 
BSD 


Linux 1.3.88, 14 April 1996 


read 


read— Reads from a file descriptor 


SYNOPSIS 


#include <unistd.h> 
ssize t read(int fd,void*buf , size_t count); 


DESCRIPTION 


read() attempts to read up to count bytes from file descriptor a into the buffer starting at but. 
If count iS, read() returns @ and has no other results. If count is greater than ss1ze_Max, the result is unspecified. 


RETURN VALUE 


On success, the number of bytes read is returned (0 indicates end of file) and thefile position is advanced by this numbex. It 
isnot an error if this number is smaller than the number of bytes requested; this may happen, for example, because fewer 
bytes are actually available right now (maybe because we were close to end-of-file or because we are reading from a pipe, or 
from a terminal), or because read() was interrupted by a signal. On error, -1 isreturned and errno is sé appropriately. In this 
case it is left unspecified whether the file position (if any) changes. 


ERRORS 

EINTR The call was interrupted by a signal before any data was read. 

EAGAIN N on-blocking I/O has been selected using 0_NonBLock and no data was immediately available for 
reading. 

EIO 1/0 error. This will happen, for example when the process isin a background process group, tries to 
read from itscontrolling tty, and it isignoring or blocking statT1N or its process group is orphaned. 

EISDIR fd refers to a directory. 

EBADF fd isnot a valid file descriptor or is not open for reading. 

EINVAL fd is attached to an object that is unsuitable for reading. 

EFAULT buf isoutside your accessible address space. 


O ther errors may occur, depending on the object connected to fa. POSIX allows a read that is interrupted after reading some 
data to return -1 (with errno set to EINTR) or to return the number of bytes already read. 


CONFORMS T0 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 


readdir(2), write(2), write(2), font1(2), close(2), lseek(2), select(2), readlink(2), ioct1(2), fread(3) 
Linux, 17 January 1996 


readlink 


readdir 


readdir— Reads directory entry 


SYNOPSIS 


#include <unistd.h> 

#include <linux/dirent.h> 

#include <linux/unistd.h> 

syscall3(int, readdir, uint, fd, struct dirent *, dirp, uint, count); 
int readdir(unsigned int fd, struct dirent *dirp, unsigned int count ); 


DESCRIPTION 


This is not the function you are interested in. Look at readdir(3) for the PO SIX-conforming C library interface. T his page 
documents the bare kernel system call interface, which can change, and which is superseded by getdents(2). 


readdir reads one dirent structure from the directory pointed at by fa into the memory area pointed to by dirp. The 
parameter count is ignored; at most one dirent structure is read. 


Thedirent structure is declared as follows: 


struct dirent 


{ 
long d_ino; /* inode number */ 
off_t d_off; /* offset to this dirent */ 
unsigned short d_reclen; /* length of this d_name */ 
char d_name [NAME_MAX+1]; /* file name (null-terminated) */ 
} 


d_ino isan inodenumber. d_oft isthe distance from the start of the directory to thisdirent. d_recien isthesize of d_ name, not 
counting the null terminator. d_name is anull-terminated filaaame 


RETURN VALUE 
On success, 1 isreturned. On end of directory, @ isreturned. On aror, -1 iSreturned and errno is set appropriately. 
ERRORS 
EBADF Invalid file descriptor fa. 
ENOTDIR File descriptor does not refer to a directory. 
CONFORMS TO 
This system call is Linux specific. 
SEE ALSO 


getdents(2), readdir(3) 
Linux 1.3.6, 22 July 1995 


readlink 


readlink— Reads value of a symbolic link 


SYNOPSIS 


#include <unistd.h> 
int readlink(const char *path, char *buf, size_t bufsiz); 
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DESCRIPTION 


readlink places the contents of the symbolic link path in the buffer buf , which has size buf siz. Readlink does not append a 
NuL character to buf. 


RETURN VALUES 


The call returns the count of characters placed in the buffer if it succeeds, or a -1 if an error occurs, placing the error code in 
the global variable errno. 


ERRORS 
ENOTDIR A component of the path prefix is not a directory. 
EINVAL The pathname contains a character with the high-order bit set. 
ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 
characters. 
ENOENT The named file does not exist. 
EACCES Search permission is denied for acomponent of the path prefix. 
ELOOP Too many symbolic links were encountered in translating the pathname 
EINVAL Thenamed file is not a symbolic link. 
EIO An 1/0 error occurred while reading from the filesystem. 
EFAULT buf extends outside the process's allocated address space. 
HISTORY 
The readiink function call appeared in BSD 4.2. 
SEE ALSO 


stat(2), lstat(2), symlink(2) 
BSD Man Page 24 July 1993 


readv, writev 


readv, writev— Reads or writes a vector 


SYNOPSIS 


#include <sys/uio.h> 

int readv(int fd, const struct iovec * vector, size_t count); 
int writev(int fd, const struct iovec * vector, size_t count); 
struct iovec { 

ptr_t iov_base; /* Starting address. */ 

size_t iov_len; /* Length in bytes. */ 

}; 


DESCRIPTION 


readv reads data from file descriptor fd and puts the result in the buffers described by vector . T henumber of buffers is 
specified by count . The buffers are filled in the order specified. O perates just like read except that data is put in vector 
instead of a contiguous buffer. 


writev writes data to file descriptor fd, and from the buffers described by vector. The number of buffersis specified by count. 
The buffers are used in the order specified. O perates just like write except that data is taken from vector instead of a 
contiguous buffer. 


readv, writev 
RETURN VALUE 


On success, readv returnsthenumber of bytes read. On success, writev returns the number of bytes written. On error, -1 is 
returned, and errno isse@ appropriately. 


ERRORS 

EINVAL An invalid argument was given. For instancecount might be greater than max_Iovec, or 0. fd could 
also be attached to an object that is unsuitable for reading. 

EFAULT Segmentation fault. M ost likely vector or someof thei ov_base pointers pointsto memory that is 
not properly allocated. 

EBADF The file descriptor fd isnot valid. 

EINTR The call was interrupted by a signal before any data was read/written. 

EAGAIN N on-blocking!/O has been selected using 0_NonBLock and no data was immediately available for 
reading. (Or the file descriptor fa is for an object that is locked.) 

EISDIR fd refers to a directory. 

EOPNOTSUP fd refers to a socket or device that does not support reading/writing. 


O ther errors may occur, depending on the object connected to fd. 


SEE ALSO 
read(2), write(2), fprintt(3), fscant(2) 
Linux 1.3.86, 12 April 1996 


reboot 
reboot— Reboots or disables Ctrl+Alt+D a 
SYNOPSIS 


#include <unistd.h> 
int reboot (int magic ,int magic_too,int flag); 


DESCRIPTION 
reboot reboots the system or enables/disables CAD . 
If magic =Oxfeetdead and magic_too =672274793, the action paformed will be based on f! ag. 
If f1ag=0x1234567, a hard reset is performed. 
If flag=0x89abcdef, CAD is abled. 
If #1ag=0, CAD is disabled and a signal is sent to process|D 1. 
N ote that reboot() does not sync()! 
Only the superuser may use this function. 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 
ERRORS 

EINVAL Bad magic numbers orflag. 


EPERM A non-root user has attempted to call reboot. 
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CONFORMS TO 


reboot is Linux specific. 


SEE ALSO 
syne(2), ctrlaltde1(8), halt(8), reboot(8) 
Linux 0.99.10, 28 M arch 1992 


recy, recvfrom, recvmsg 


recv, recvfrom, recvmsg— Receives a message from a socket 


SYNOPSIS 


#include <sys/types.h> 

#include <sys/socket.h> 

int recv(int s, void *buf , intlen, unsigned int flags); 

int recvfrom(int s, void*buf , int len, unsigned int flags, 
struct sockaddr *from, int *fromlen); 

int recvmsg(int s, struct msghdr *msg, unsigned int flags); 


DESCRIPTION 
Warning: ThisisaBSD man page As of Linux 0.99.11, recvmsg was not implenented. 


recvfrom and recvmsg are used to receive messages from a socket, and may be used to receive data on a socket whether or not 
it isconnection oriented. 


If fromiSnon-nil, and the socket is not connection-oriented, the source address of the message is filled in. fromien isavalue 
result parameter, initialized to the size of the buffer associated with from and modified on return to indicate the actual size of 
the address stored there. 


The recv call is normally used only on a connected socket (see connect(2)) and isidentical to recvfrom with anil from 
parameter. Because it is redundant, it might not be supported in future releases. 


All three routines return the length of the message on successful completion. If a message is too long to fit in the supplied 
buffer, excess bytes might be discarded depending on the type of socket from which the message is received (See socket(2)). 


If no messages are available at the socket, the receive call waits for a message to arrive— unless the socket is nonblocking (see 
fent1(2)), in which case the value -1 isreturned and the external variable errno is set to EWOULDBLOCK. T he receive calls 
normally return any data available, up to the requested amount, rather than wait for recdipt of the full amount requested; 
this behavior is affected by the socket-leved options so_RcvLowaT and so_RcVvTIMEO, described in getsockopt(2). 


The select(2) call may be used to determine when more data arrives. 
Thefl ags argument to a recv call is formed by oring one or more of the values: 


MSG_00B Process out-of-band data 
MSG_PEEK Peek at incoming message 
MSG_WAITALL W ait for full request or error 


Themsc_oos flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols 
place expedited data at the head of the normal data queue; thus this flag cannot be used with such protocols. Themsc_PEEK 
flag causes the receive operation to return data from the beginning of the recd ve queue without removing that data from the 
queue; thus, a subsequent receive call will return the same data. The msc_waITALt flag requests that the operation block until 
the full request is satisfied. H owever, the call might still return less data than requested if a signal is caught, an error or 
disconnect occurs, or the next data to be received is of a different type than that returned. 
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The recvmsg Call uSeS a msghdr structure to minimize the number of directly supplied parameters. T his structure has the 
following form, as defined in sys/socket.h: 
struct msghdr { 
caddr_t msg_name; /* optional address */ 
u_int msg_namelen; /* size of address */ 
struct iovec *msg_iov; /* scatter/gather array */ 
u_int msg_iovlen; /* # elements in msg iov */ 
caddr_t msg_control; /* ancillary data, see below */ 
u_int msg_controllen; /* ancillary data buffer len */ 
int msg_flags; /* flags on received message */ 
}; 


Here msg_name and msg_namelen specify the destination address if the socket is unconnected; msg_name may be given asa null 
pointer if no names are desired or required. msg_iov and msg_iovilen describe scatter gather locations, as discussed in read(2). 
msg_control, which has length msg_controllen, points to a buffer for other protocol control-related messages or other 
miscellaneous ancillary data. The messages are of the form 
struct cmsghdr { 

u_int cmsg_len; /* data byte count, including hdr */ 

int cmsg_level; /* originating protocol */ 

int cmsg_type; /* protocol-specific type */ 
/* followed by 

u_char cmsg_data[]; */ 
hs 


You could use this, for example to learn of changes in the data stream in XN S/SPP, or in ISO, to obtain user- 
connection-request data by requesting a recvmsg with no data buffer provided immediately after an accept call. 


Open file descriptors are now passed as ancillary data for aF_uN1x domain sockets, with cmsg_level set to SoL_SocKET and 
cmsg_type Set to SCM_RIGHTS. 


Themsg_flags field is set on return according to the message received. msG_Eor indicates end-of-record; the data returned 
completed a record (generally used with sockets of type sock_SEQPACKET). MSG_TRUNC indicates that the trailing portion of a 
datagram was discarded because the datagram was larger than the buffer supplied. msc_ctrunc indicates that some control 
data was discarded due to lack of space in the buffer for ancillary data. msc_oos is returned to indicate that expedited or out- 
of-band data was received. 


RETURN VALUES 
T hese calls return the number of bytes received, or -1 if an error occurred. 
ERRORS 
EBADF The argument s isan invalid descriptor. 
ENOTCONN The socket is associated with a connection-oriented protocol and has not been connected (see 
connect(2) and accept(2)). 
ENOTSOCK Theargument s does not refer to a socket. 
EWOULDBLOCK The socket is marked non-blocking, and the rec ve operation would block, or a receive timeout 
had been set, and the timeout expired before data was rece ved. 
EINTR The receive was interrupted by delivery of a signal before any data was available 
EFAULT The receive buffer pointer(s) point outside the process's address space. 
HISTORY 


T hese function calls appeared in BSD 4.2. 
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SEE ALSO 


fentl(2), read(2), select(2), getsockopt(2), socket(2) 


rename 


BSD Man Page 24 July 1993 


rename— Changes thename or location of afile 


SYNOPSIS 


#include <unistd.h> 


int rename(const char *oldpath, const char *newpath); 


DESCRIPTION 


rename renames a file, moving it between directories if required. 
Any other hard links to the file (as created using link) are unaffected. 


If newpath already exists it will be automatically overwritten (subject to a few conditions— see the “Errors” section), so that 
there isno point at which another process attempting to access newpath will find it missing. 


If newpath exists but the operation fails for some reason or the system crashes, rename guarantees to leave an instance of 


newpath in place. 


H owever, when overwriting there will probably be a window in which both ol dpath and newpath refer to thefile being 


renamed. 


If ol dpath refers to asymbolic link, the link will be renamed; if newpath refersto a symbolic link, the link will be overwritten. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 


EISDIR 
EXDEV 
ENOTEMPTY 
EBUSY 
EINVAL 
EMLINK 


ENOTDIR 
EFAULT 
EACCES 


EPERM 


ENAMETOOLONG 
ENOENT 
ENOMEM 

EROFS 


newpa 
oldpa 
newpa 


newpa 


isan existing directory, but 0! dpath isnot a directory. 

and newpath arenot on thesame filesystem. 

isanon-empty directory. 

exists and isthecurrent working directory or root directory of some process. 


An attempt was madeto make a directory a subdirectory of itself. 


oldpa 


already has the maximum number of links to it, or it was a directory and the directory 


containing newpath has the maximum number of links. 


Acom 


oldpa 


ponent used as a directory in ol dpath Or newpath iSnot, in fact, a directory. 
Or newpath points outside your accessible address space. 


W rite access to the directory containingol dpath Ornewpath isnot allowed for the process's effective 
UID, or oneof thedirectoriesin ol dpath Of newpath did not allow search (execute) permission, or 








oldpa 


Thedi 
UID o 


was a directory and did not allow write permission (needed to update the .. entry). 


rectory containing o! dpath has the sticky bit set, and the process's effective UID is neither the 
f the file to be ddeted nor that of the directory containing it, or the filesystem containing 


pathname does not support renaming of the type requested. 
oldpath Or newpath was too long. 
A directory componentin ol dpath Or newpath does not exist or isa dangling symbolic link. 





Insuffi 
Thefil 


cient kernel memory was available. 
eis on aread-only filesystem. 


ELOOP oldpath Of newpath Containsa reference to a circular symbolic link; that is, a symbolic link whose 
expansion contains a reference to itself. 
ENOSPC The device containing the file has no room for the new directory entry. 
CONFORMS TO 
POSIX, BSD 4.3, ANSI C 
BUGS 


Currently (Linux 0.99p!7), most of the filesystems except M inix will not allow any overwriting renames involving directories. 
You get Eexist if you try. 


On NFS filesystems, you cannot assume that just because the operation failed, the file was not renamed. If the server does 
the rerame operation and then crashes, the retransmitted RPC, which will be processed when the server is up again, causes a 
failure. T he application is expected to deal with this. See 1ink(2) for a similar problem. 


SEE ALSO 
link(2), unlink(2), symlink(2), mv(1), 1ink(8) 
Linux 0.99.7, 24 July 1993 


rmdir 


rmdir— D detes a directory 


SYNOPSIS 


#include <unistd.h> 
int rmdir(const char *pathname); 


DESCRIPTION 
rmdir deletes a directory, which must be empty. 
RETURN VALUE 
On success, 0 isreturned. On error, -1 is returned, and errno is set appropriately. 
ERRORS 
EPERM The filesystem containing pathname doesnot support the renoval of directories. 
EFAULT pathname points outside your accessible address space. 
EACCES W rite access to the directory containing pat hname was not allowed for the process's effective UID , 
or one of thedirectoriesin pathname did not allow search (execute) permission. 
EPERM The directory containing pathname has thesticky bit (s_tsvtx) set, and the process's effective UID is 
nathe theUID of the file to be deleted nor that of the directory containing it. 
ENAMETOOLONG athname was too long. 
ENOENT A directory component in pat hname does not exist or isa dangling symbolic link. 
ENOTDIR athname, OF acomponent used as a directory in pathname, iS not, in fact, adirectory. 
ENOTEMPTY athname contains entries other than . and ... 
EBUSY athname isthe current working directory or root directory of some process. 
ENOMEM Insufficient kernel memory was available. 
EROFS athname refersto afile on aread-only filesysten. 
ELOOP athname Contains a reference to a circular symbolic link; that is, asymbolic link containing a 











reference to itself. 
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CONFORMS TO 
SVID, AT&T, POSIX, BSD 4.3 


BUGS 


Infdicities in the protocol underlying N FS can cause the unexpected disappearance of directories that are still being used. 


SEE ALSO 
rename(2), mkdir(2), chdir(2), unlink(2), rmdir(1), rm(1) 
Linux 0.99.7, 24 July 1993 


sched get_priority_max, sched get_priority_min 


sched_get_priority_max, sched_get_priority_min— Gets static priority range 


SYNOPSIS 


#include <sched.h> 
int sched_get_priority_max(int policy); 
int_sched_get_priority_min(int policy); 


DESCRIPTION 
sched_get_priority_max returns the maximum priority value that can be used with the scheduling algorithm identified by 
policy. sched_get_priority_min returns the minimum priority value that can be used with the scheduling algorithm 
identified by policy. Supported policy values are SCHED FIFO, SCHED_RR, aNd SCHED_OTHER. 
Processes with numerically higher priority values are scheduled before processes with numerically lower priority values. 
Therefore, the value returned by sched_get_priority_max will be greater than the value returned by sched_get_priority_min. 
Linux allows the static priority value range 1 to 99 for scHED_FIFO and scHED_RR, and the priority 0 for scHED_OTHER. 
Scheduling priority ranges for the various policies are not alterable. 
The range of scheduling priorities may vary on other PO SIX systems, so it isa good idea for portable applications to usea 
virtual priority range and map it to the interval given by sched_get_priority_max and sched_get_priority_min. POSIX.1b 
requires a spread of at least 32 between the maximum and the minimum values for ScHED_FIFO and SCHED RR. 


POSIX systems on which sched_get_priority_max and sched_get_priority_min are available define 
_POSIX_PRIORITY_SCHEDULING in <unistd.h>. 


RETURN VALUE 


On SUCCESS, sched_get_priority_max and sched_get_priority_min return the maximum and minimum priority values for the 
named scheduling policy. On error, -1 is returned, and errno is set appropriately. 


ERRORS 

EINVAL The parameter policy does not identify a defined scheduling policy. 
STANDARDS 

POSIX.1b (formerly PO SIX.4) 
SEE ALSO 


sched_setscheduler(2), sched_getscheduler(2), sched_setparam(2), sched_getparam(2) 
sched_setscheduler(2) has a description of the Linux scheduling scheme. 


sched_rr_get_interval 


Programming for the Real W orld— POSIX.4 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.1b-1003 (PO SIX.1b standard) 
ISO/IEC 9945-1:1996 
Linux 1.3.81, 10 April 1996 


sched rr_get_interval 


sched_rr_get_interval— Gets the scHED_rr interval for the named process 


SYNOPSIS 


#include <sched.h> 
int sched_rr_get_interval(pid_t pid, struct timespec *tp); 
struct timespec { 
time_t tv_sec; /* seconds */ 
long tv_nsec; /* nanoseconds */ 
hs 


DESCRIPTION 


sched_rr_get_interval writes into theti mespec structure pointed to by tp the round-robin time quantum for the process 
identified by pid. If pid iso, the time quantum for the calling process is written into *t p. Theidentified process should be 
running under the scHep_rr scheduling policy. 


Theround robin time quantum value is not alterable under Linux 1.3.81. 
POSIX systems on which sched_rr_get_interval is available define posIx_PRIORITY SCHEDULING iN <unistd.h>. 


RETURN VALUE 
On success, sched_rr_get_interval returns o. On error, -1 is returned, and errno is set appropriately. 
ERRORS 
ESRCH The process whose ID ispid could not be found. 
ENOSYS Thesysten call isnot yet implemented. 
STANDARDS 
POSIX.1b (formerly PO SIX.4) 
BUGS 


As of Linux 1.3.81, sched_rr_get_interval returns with error ENosys, because scHED_RR has not yet been fully implemented or 
tested properly. 
SEE ALSO 
sched_setscheduler(2) has a description of the Linux scheduling scheme. 
Programming for the Real W orld— POSIX.4 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.1b-1993 (PO SIX.1b standard) 
ISO/IEC 9945-1:1996 
Linux 1.3.81, 10 April 1996 
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sched setparam, sched getparam 


sched_setparam, sched_getparam— Sets and get scheduling parameters 


SYNOPSIS 


#include <sched.h> 

int sched_setparam(pid_t pid, const struct sched_param *p); 
int sched_getparam(pid_t pid, struct sched_param *p); 
struct sched_param { 


int sched_priority; 
}; 
DESCRIPTION 


sched_setparam sets the scheduling parameters associated with the scheduling policy for the process identified by pid. If pid is 
o, the parameters of the current process are set. T he interpretation of the parameter p depends on the selected policy. 
Currently, the following three scheduling policies are supported under Linux: SCHED FIFO, SCHED_RR, and SCHED_OTHER. 


sched_getparam retrieves the scheduling parameters for the process identified by pid. If pid iso, the parameters of the current 
process are retrieved. 


sched_setparam checks the validity of p for thescheduling policy of the process. T he parameter p->sched_priority must lie 
within the range given by sched_get_priority_min and sched_get_priority_max. 


POSIX systems on which sched_setparam and sched_getparam are available define _POSIX_PRIORITY_SCHEDULING in <unistd.h>. 


RETURN VALUE 
On SUCCESS, sched_setparam and sched_getparam return @.On error, -1 iS returned, and errno is set appropriately. 
ERRORS 

ESRCH The process whose ID ispid could not be found. 

EPERM The calling process does not have appropriate privileges. T he process calling sched_setparam needs 
an effective UID equal to the UID or UID of the process identified by pid, or it must bea 
superuser process. 

EINVAL The parameter p does not make sense for the current scheduling policy. 

STANDARDS 
POSIX.1b (formerly PO SIX.4) 
SEE ALSO 


sched_setscheduler(2), sched_getscheduler(2), sched_get_priority_max(2), sched_get_priority_min(2), nice(2), 
setpriority(2), getpriority(2) 


sched_setscheduler(2) has a description of the Linux scheduling scheme. 
Programming for the Real W orld— POSIX.4 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.1b-1993 (PO SIX.1b standard) 
ISO/IEC 9945-1:1996 
Linux 1.3.81, 10 April 1996 


sched_sétscheduler, sched_getscheduler 


sched setscheduler, sched getscheduler 


sched_setscheduler, sched_getscheduler— Sets and gets scheduling algorithm/parameters 


SYNOPSIS 


#include <sched.h> 

int sched_setscheduler(pid_t pid,intpolicy, const struct sched_param *p); 
int sched_getscheduler(pid_t pid); 

struct sched_param { 


int sched_priority; 
}; 
DESCRIPTION 


sched_setscheduler sets both the scheduling policy and the associated parameters for the process identified by pid. If pid iso, 
the scheduler of the calling process will be set. The interpretation of the parameter p depends on the sdected policy. 
Currently, the following three scheduling policies are supported under Linux: SCHED FIFO, SCHED_RR, aNd SCHED_OTHER; their 
respective semantics are described in the following section. 


sched_getscheduler queries the scheduling policy currently applied to the process identified by pid. If pid ise, the policy of 
the calling process will be retrieved. 


SCHEDULING POLICIES 


The scheduler is the kernel part that decides which runnable process will be executed next by the CPU. The Linux scheduler 
offers three different scheduling policies, one for normal processes and two for real-time applications. A static priority value, 
sched priority, IS assigned to each process, and this value can be changed only via systen calls. Conceptually, the scheduler 
maintains a list of runnable processes for each possiblesched_priority value, and sched_priority can haveavaluein the 
range 0 to 99. To determine the process that runs next, the Linux scheduler looks for the non-empty list with the highest 
static priority and takes the process at the head of this list. T he scheduling policy determines, for each process, where it will 
be inserted into the list of processes with equal static priority and how it will move inside this list. 


SCHED_OTHER iS the default universal time-sharing scheduler policy used by most processes; SCHED_FIFO and SCHED_RR are 
intended for special, time-critical applications that need precise control over the way in which runnable processes are sel ected 
for execution. Processes scheduled with scHED_OTHER must be assigned the static priority 0; processes scheduled under 
SCHED_FIFO OF SCHED_RR Can havea static priority in the range 1 to 99. Only processes with superuser privileges can get a static 
priority higher than 0 and can therefore be scheduled under scHED_FIFO Or SCHED_rR. T he system calls sched_get_priority_min 
and sched_get_priority_max Can be used to find out the valid priority range for a scheduling policy in a portable way on all 
POSIX.1b-conforming systems. 


All scheduling is preemptive: If a process with a higher static priority gets ready to run, the current process will be preempted 
and returned into its wait list. The scheduling policy determines the ordering within the list of runnable processes only 
among those with equal static priority. 


SCHED FIFO: FIRST IN-FIRST OUT SCHEDULING 


SCHED_FIFO Can only be used with static priorities higher than 0, which means that when a scHED_FIFO process becomes 
runnable, it will always preempt immediatdy any currently running normal scHED_OTHER PrOCess. SCHED_FIFO iSasimple 
scheduling algorithm without time slicing. 


For processes scheduled under the scHep_FIFo policy, the following rules are applied: A scHED_FIFo process that has been 
preempted by another process of higher priority will stay at the head of the list for its priority and will resume execution as 
soon asall processes of higher priority are blocked again. When ascHED_FIFO process becomes runnable, it will be inserted at 
the end of the list for its priority. A call to sched_setscheduler Or sched_setparam Will put the scHED_FIFO process identified by 
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pid at the end of the list if it was runnable A process calling sched_yie1d will be put at the end of the list. No other events 
will move a process scheduled under the scHep_F1Fo policy in the wait list of runnable processes with equal static priority. A 
SCHED_FIFO processruns until it is blocked by an 1/O request, it is preempted by a highe-priority process, or it calls 
sched_yield. 


SCHED RR: ROUND-ROBIN SCHEDULING 


SCHED_RR iS a simple enhancement of scHeD_F1Fo. Everything described in the preceding section for scHED_FIFo also applies to 
SCHED_RR, except that each process is only allowed to run for amaximum time quantum. If a scHED_RR process has been 
running for atime period equal to or longer than the time quantum, it will be put at the end of the list for its priority. A 
SCHED_RR process that has been preempted by a highe-priority process and subsequently resumes execution as a running 
process will complete the unexpired portion of its round-robin time quantum. T helength of the time quantum can be 
retrieved by sched_rr_get_interval. 


SCHED OTHER: DEFAULT LINUX TIME-SHARING SCHEDULING 
SCHED_OTHER Can only be used at static priority 0. scHED_oTHER is the standard Linux time-sharing scheduler that is intended 
for all processes that do not require special static-priority real-time mechanisms. T he process to run is chosen from the static 
priority 0 list based on a dynamic priority that is determined only inside this list. The dynamic priority is based on the nice 
level (set by the nice or setpriority system call) and is increased for each time quantum the process is ready to run but is 
denied to run by the scheduler. T his ensures fair progress among all ScHED_OTHER Processes. 


RESPO NSE TIME 
A blocked high-priority process waiting for the!/O has a certain response time before it is scheduled again. T he device driver 
writer can greatly reduce this response time by using a dow interrupt interrupt handler, as described in request irq(9). 
MISCELLANEOUS 
Child processes inherit the scheduling algorithm and parameters across a fork. 
M emory locking is usually needed for real-time processes to avoid paging ddays; this can be done with mlock Or mlockall. 


Because a non-blocking endless loop in a process scheduled under scHED_FIFO Or SCHED_RR Will block all processes with lower 
priority forever, a software devdoper should always keep available on the console a shell scheduled under a higher static 
priority than the tested application. This will allow an emergency kill of tested real-time applications that do not block or 
terminate as expected. Because SCHED_FIFO and SCHED_RR processes can preempt other processes forever, only root processes 
are allowed to activate these policies under Linux. 


POSIX systems on which sched_setscheduler and sched_getscheduler are available define _posIx_PRIORITY_SCHEDULING in 
<unistd.h>. 


RETURN VALUE 


On SUCCESS, sched_setscheduler returns 0. On SUCCESS, sched_getscheduler returns the policy for the process (a non-negative 
integer). On error, -1 isreturned, and errno is set appropriately. 


ERRORS 
ESRCH The process whose ID ispid could not be found. 
EPERM The calling process does not have appropriate privileges. O nly root processes are allowed to activate 


the scHED_FIFO and SCHED_rR policies. The process calling sched_setscheduler needs an effective 
UID equal to the EUID or UID of the process identified by pid, or it must be a superuser process. 


EINVAL The scheduling policy is not one of the recognized policies, or the parameter p does not make sense 
for the policy. 


STANDARDS 
POSIX.1b (formerly PO SIX.4) 


sdect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO 
BUGS 


As of Linux 1.3.81, scHep_rr has not yet been tested carefully and might not behave exactly as described or required by 
POSIX.1b. 
SEE ALSO 


sched_setparam(2), sched _getparam(2), sched_yield(2), sched_get_priority_max(2), sched_get_priority_min(2), nice(2), 
setpriority(2), getpriority(2), mlockall(2), munlockall(2), mlock(2), munlock(2). 


Programming for the Real W orld— POSIX.4 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.1b-1003 (PO SIX.1b standard) 


ISO/IEC 9945-1:1996—T his isthe new 1996 revision of PO SIX.1, which contains in one single standard PO SIX.1(1990), 
POSIX.1b(1993), PO SIX.1¢(1995), and PO SIX.1i(1995), 
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sched yield 


sched_yield— Yields the processor 


SYNOPSIS 


#include <sched.h> 
int sched_yield(void) ; 


DESCRIPTION 


A process can relinquish the processor voluntarily without blocking by calling sched_yield. T he process will then be moved 
to the end of the queue for its static priority and a new process gets to run. 


N ote: If the current process is the only process in the highest priority list at that time this process will continue to run afte a 
call to sched_yield. 


POSIX systems on which sched_yield iS available define PosIx_PRIORITY_SCHEDULING in <unistd.h>. 


RETURN VALUE 


On success, sched_yield returns a. On error, -1 isreturned, and errno is set appropriately. 


STANDARDS 
POSIX.1b (formerly PO SIX.4) 


SEE ALSO 
sched_setscheduler(2) for a description of Linux scheduling 
Programming for the Real W orld— POSIX.4 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.1b-1993 (PO SIX.1b standard) 
ISO/IEC 9945-1:1996 
Linux 1.3.81, 10 April 1996 


select, FD CLR, FD ISSET,FD SET, FD ZERO 


select, FD_CLR, FD_ISSET, FD_SET, FD_ZERO— Synchronous I/O multiplexing 
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SYNOPSIS 


#include <sys/time.h> 

#include <sys/types.h> 

#include <unistd.h> 

int select(int n,fd_set *readfds ,fd_set *writefds,fd_set *exceptfds, 
struct timeval *timeout ); 

FD_CLR(int fd,fd_set *set); 

FD_ISSET(int fd,fd_set *set); 

FD_SET(int fd,fd_set *set); 

FD_ZERO(fd_set *set ) 


DESCRIPTION 


select waits for anumber of file descriptors to change status. 


Three independent sets of descriptors are watched. Those listed inreadfds will be watched to seeif characters become 
available for reading, thosein writefds will be watched to see if it is okay to immediately write on them, and those in 
exceptfds will be watched for exceptions. On exit, the sets are modified in place to indicate which descriptors actually 
changed status. 


Four macros are provided to manipulate the sets. Fp_zero will clear a set. FD_SeT and FD_cLr add or remove a given descriptor 
from a set. FD_rsseT tests to seeif a descriptor is part of the set; this is useful after select returns. 


n isthe highest-numbered descriptor in any of the three sets, plus 1. 


timeout iSan upper bound on the amount of time dapsed before select returns. It may be a, which causes select to return 
immediately. If timeout iS NULL (no timeout), select can block indefinitely. 


RETURN VALUE 


On success, select returns the number of descriptors contained in the descriptor sets, which may bea if the timeout expires 
before anything interesting happens. On error, -1 is returned, and errno is set appropriately; the sets and ti meout become 
undefined, so do not rely on their contents after an error. 


ERRORS 
EBADF An invalid file descriptor was given in one of the sets. 
EINTR A non-blocked signal was caught. 
EINVAL n is negative. 
ENOMEM select was unable to allocate memory for internal tables. 
NOTES 


Some code calls select with all three sets enpty, n=0, and anon-null timeout; this is a fairly portable way to sleep with 
subsecond precision. 


On Linux, timeout ismodified to reflect the amount of time not sleot; most other implementations do not do this. This 
causes problems both when Linux code that reads timeout is ported to other operating systems and when codeis ported to 
Linux that reuses a struct timeval for multiple selectsin aloop without rdinitializing it. Consider timeout to be undefined 
after select returns. 


EXAMPLE 


#include <stdio.h> 
#include <sys/time.h> 
#include <sys/types.h> 
#include <unistd.h> 


int 


main(void) 


{ 


} 


fd_set rfds; 
struct timeval tv; 
int retval; 


/* Watch stdin (fd @) to see when it has input. */ 
FD_ZERO(&rfds) ; 

FD_SET(®, &rfds); 

/* Wait up to five seconds. */ 

tv.tv_sec = 5; 

tv.tv_usec = Q; 


retval = select(1, &rfds, NULL, NULL, &tv); 
/* Don't rely on the value of tv now! */ 


if (retval) 

printf("Data is available now.nn"); 

/* FD_ISSET(®, &rfds) will be true. */ 
else 

printf("No data within five seconds.nn"); 
exit(Q); 


SEE ALSO 


accept(2), connect(2), read(2), recv(2), send(2), write(2) 


semctl 


semct1— Senaphore-control operations 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/sem.h> 


int semctl ( int semid,int semnun,int cmd, union semun arg ); 


DESCRIPTION 


The function performs the control operation specified by cmd on the semaphore set (or on thes umun-nth semaphore of the 


set) identified by semi d. The first sanaphore of the set isindicated by a value of @ for semun. 


The type of arg isthe union 


union semun { 


}; 


int val; /* used for SETVAL only */ 
struct semid_ds *buf; /* for IPC_STAT and IPC_SET */ 
ushort *array; /* used for GETALL and SETALL */ 


Legal values for cmd are 


IPC_STAT 
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Copies info from the sanaphore set data structure into the structure pointed to by arg .buf. The 


argument semnum isignored. The calling process must have read access privileges on the semaphore set. 
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IPC_SET 


IPC_RMID 


GETALL 


GETNCNT 


GETPID 


GETVAL 


GETZCNT 


SETALL 


SETVAL 


RETURN VALUE 


W rites the values of some menbers of the semid_ds structure pointed to by arg .buf to the sanaphore 
set data structure, updating also its sem_ctime member. Considered members from the user-supplied 
struct semid_ds pointed to by arg. buf are 

sem_perm.uid 

sem_perm.gid 

sem_perm.mode /* only lowest 9-bits */ 

The calling process's effective user |D must be super- user, creator, or owner of the semaphore set. T he 
argument semnum is ignored. 

Removes the semaphore set and its data structures immediate y, awakening all waiting processes (with 
an error return and errno set to EID RM ). The calling process's effective user ID must be super-user, 
creator, or owner of the semaphore set. The argument s emnum is ignored. 


Returns semvai for all semaphores of the set into arg.array. The argument semnum iSignored. The 
calling process must have read access privileges on the sanaphore set. 

The system call returns the value of semncnt for the semno-th sanaphore of the set (that is, the number 
of processes waiting for an increase of semva1 for thes emno-th semaphore of the set). The calling 
process must have read access privileges on the semaphoreset. 


The systan call returns the value of sempid for the semno-th semaphore of the set (that is, the pia of the 
process that executed the last semop call for thes emno-th semaphore of the set). The calling process 
must have read access privileges on the semaphore set. 

The system call returns the value of semval for thes emno-th semaphore of the set. The calling process 
must have read access privileges on the semaphore set. 


The system call returns the value of semzcnt for the semno-th sanaphore of the set (that is, the number 
of processes waiting for the semva1 of thesemno-th semaphore of the set to become 0). T he calling 
process must have read access privileges on the semaphore set. 

Sets semval for all semaphores of the set using arg .array, updating also the sem_ctime manber of the 
semid_ds structure associated with the set. U ndo entries are cleared for altered semaphores in all 
processes. Processes sleeping on the wait queue are awakened if some semval becomes a or increases. 
The argument semnum isignored. The calling process must have alter access privileges on the sanaphore 
set. 

Sets the value of semval to arg .val for thes emnum-th semaphore of the set, updating also the sem_ctime 
member of the semid_ds structure associated to the set. The undo entry is cleared for the altered 
semaphore in all processes. Processes sleeping on the wait queue are awakened if semval become 0 or 
increases. T he calling process must have alter access privileges on the semaphore set. 











On fail, the system call returns -1, with errno indicating the error. O therwise the system call returns a non-negative value, 
depending on cmd, as follows: 


GETNCNT 
GETPID 
GETVAL 
GETZCNT 


ERRORS 


The value of semnent. 
The value of sempid. 
The value of semval. 
The value of semzent. 


For a failing return, errno will be set to one of the following values: 


EACCESS 
EFAULT 
EIDRM 
EINVAL 





The calling process has no access permissions needed to execute cmd. 
The address pointed to by arg .buf or arg .array isn’t accessible 
The semaphore set was renoved. 

Invalid value for cmd orsemid. 


EPERM The argument cmd has the value rpc_set or 1Pc_amip, but the calling process's effective user ID has 
insufficient privileges to execute the command. 
ERANGE The argument cmd has the value seTALt or seTVAL, and the value to which semva1 has to be set (for some 


semaphore of the set) is less than 0 or greater than the implementation value semvax. 


NOTES 


The IpC_INFO, SEM_STAT, and SEM_INFO control calls are used by the ipcs(1) program to provide information on allocated 
resources. In the future these can be modified as needed or moved to aproc filesystem interface. 


The following system limit on semaphore sets affects a semct1 Call: 
SEMVMX M aximum value for semval; implementation dependent (32767). 


SEE ALSO 


ipc(5), shmget(2), shmat(2), shmdt(2) 
Linux 0.99.13, 1 November 1993 


semget 


semget— Gets a semaphore set identifier 


SYNOPSIS 


# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/sem.h> 

int semget ( key_t key,int nsems ,int semflg ); 


DESCRIPTION 


This function returns the semaphore set identifier associated with the value of the argument key. A new set of ns ems 
semaphores is created if key has the value 1Pc_PRIVATE OF key isn’t IPC_PRIVATE, if no existing message queue is associated to 
key, and if 1pc_CREAT is asserted in semflg (that is, semf1g& 1Pc_CREAT isn’t 0). Thepresencein semfig of the fields 1pc_CcREAT 
and rpc_eExcL plays the same role, with respect to the existence of the semaphore set, as the presence of o_cREAT and 0_EXcL in 
the mode argument of the open(2) system call— that is, the msgget function fails ifs emf! g asserts both 1pc_cREAT and IPC_EXCL 
and a semaphore set already exists for key. 


Upon creation, the lower 9 bits of the argument semt!g define the access permissions (for owner, group, and others) to the 
semaphore set in the same format, and with the same meaning, as for the access permissions parameter in the open(2) or 
creat(2) system call (although the execute permissions arenot used by the system, and theterm write permissons, for a 
semaphore set, effectivey means alter permissions). 





Furthermore, while creating, the system call initializes the systan semaphore set data structure semid_ds as follows: 


sem_perm.cuid and sem_perm.uid are sé to the effective user |D of the calling process. 
sem_perm.cgid and sem_perm.gid are sé to the effective group ID of the calling process. 
The lowest-order 9 bits of sem_perm.mode are s@t to the lowest-order 9 bits of semflg. 
sem_nsems iS set to the value of ns ems. 

sem_otime iSse to 0. 

sem_ctime iS set to the current time. 


The argument nsems can be 0 (a “don’t care’) when the system call isn’t create(2). O therwise, nsems must be greater than 0 
and less or equal to the maximum number of semaphores per semid (SEMMSL). 


If the sanaphore set already exists, the access permissions are verified, and a check is made to seeif it is marked for destruc- 
tion. 
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RETURN VALUE 


If successful, the return value will be the semaphore set identifier (a positive integer); otherwise it will be-1, with errno 
indicating the error. 


ERRORS 


For a failing return, errno will be set to one of the following values: 


EACCES A semaphore set exists for key, but the calling process has no access permissions to the set. 

EEXIST A semaphore set exists for key, and sem! g was asserting both 1Pc_cREAT and IPC_EXCL. 

EIDRM The semaphore set is marked to be deleted. 

ENOENT N o semaphore set exists for key, and semf1g wasn’t asserting IPC_CREAT. 

ENOMEM A semaphore set has to be created, but the system does not have enough memory for the new data 
structure, 

ENOSPC A semaphore set has to be created, but the system limit for the maximum number of sanaphore 


sets (Semmnt) or the system-wide maximum number of semaphores (sewmns) would be exceeded. 


NOTES 


IPC_PRIVATE isn't a flag fidd but a key_t type If this special value is used for key, the system call ignores everything but the 
lowest-order 9 bits of s emf! g and creates a new semaphore set (on success). 


The followings are limits on semaphore set resources affecting asemget call: 


SEMMNI System-wide maximum number of semaphore sets; policy dependent. 
SENMSL M aximum number of semaphores per semid; implementation dependent (500 currently). 
SEMMNS System-wide maximum number of semaphores; policy dependent. A value greater than 


SEMMSLXSEMMNI Makes it irrelevant. 


BUGS 
Use of 1pc_PRIvATE doesn’t inhibit other processes’ access to the allocated semaphore set. 


As for the files, there is currently no intrinsic way for a process to ensure exclusive access to a semaphore set. Asserting both 
IPC_CREAT and IPC_EXCL iN semf! g only ensures (on success) that anew semaphore set will be created; it doesn’t imply 
exclusive access to the semaphore set. 


T he data structure associated with each semaphore in the set isn’t initialized by the system call. In order to initialize those 
data structures, you have to execute a subsequent call to semct1(2) to perform asETVAL Or a SETALL Command on the 
semaphore set. 


SEE ALSO 
ftok(3), ipc(5), semct1(2), semop(2) 
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semop 


semop— Semaphore operations 


SYNOPSIS 


# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/sem.h> 

int semop ( int semid,struct sembuf *sops, unsigned nsops ); 


DESCRIPTION 


The function performs operations on selected menbers of the semaphore set indicated by semid. Each of thensops dements 
in thearray pointed to bysops specifies an operation to be performed on a semaphore by a struct sembut including the 
following members: 

short sem_num; /* semaphore number: @ = first */ 


short sem_op; /* semaphore operation */ 
short sem_flg; /* operation flags */ 


Flags recognized in sem_flg are IPC_NOWAIT and SEm_UNDO. If an Operation asserts sem_uNpo, it will be undone when the process 
exits. 

The systan call sanantic assures that the operations will be performed if and only if all of them will succeed. Each operation 
is performed on the sem_num-th semaphore of the semaphore set, where the first semaphore of the set is semaphore 0 and is 
one of the following three 


If sem_op isa positive integer, the operation adds this value to semval. Furthermore, if sem_unpo is asserted for this 
operation, the system updates the process undo count for this sanaphore. T he operation always goes through, so no 
process sleeping can happen. The calling process must have alter permissions on the semaphore set. 

If sem_op iS, the process must have read access permissions on the semaphore se. If semval iS a, the operation goes 
through. O therwise, if 1pc_nowarT is asserted in sem_f1g, the systan call fails (undoing all previous actions performed), 
with errno set to EAGAIN. O therwise, semzcnt isincremented by 1, and the process sleeps until one of the following 
occurs: 

HM ssemval becomes, at which timethe value of semzcnt is decremented. 

M = Thesenaphore set is removed, causing the system call to fail with errno set to EIDRM. 

Mm Thecalling process receives a signal that hasto be caught; which causes the value of semzent to be decremented and 
the system call to fail with errno set to EINTR. 

Hi sIf sem_op is less than 0, the process must have alter permissions on the semaphore set. If semval is greater than or equal to 
the absolute value of sem_op, the absolute value of sem_op is subtracted by semval. Furthermore, if sem_unpo is asserted for 
this operation, the system updates the process undo count for this samaphore Then the operation goes through. 
Otherwise if 1pc_Nowart is asserted in sem_f1g, the system call fails (undoing all previous actions performed), with errno 
set to EAGAIN. O therwise, semnent isincremented by 1 and the process sleeps until one of the following occurs: 

HM ssemval becomes greater than or equal to the absolute value of sem_op, at which time the value of semncnt is 
decremented, the absolute value of sem_op is subtracted from semvai and, if sem_unpo is asserted for this operation, 
the system updates the process undo count for this semaphore. 

mM = Thesemaphore set is removed from the system: the system call fails, with errno set to EIDRM. 

MH Thecalling process receives a signal that hasto be caught; the value of semncnt is decremented, and the system call 
fails with errno set to EINTR. 


In case of success, the sempid member of the structure sem for each semaphore specified in the array pointed to bysops isset 
to the process ID of the calling process. Furthermore both sem_otime and sem_ctime are set to the current time 


RETURN VALUE 
If successful, the system call returns @; otherwise it returns -1, with errno indicating the error. 
ERRORS 
For a failing return, errno will be set to one of the following values: 
E2BIG The argument nsops iS greater than semopm, the maximum number of operations allowed per system 
call. 
EACCES The calling process has no access permissions on the sanaphore set as required by one of the specified 
operations. 
EAGAIN An operation could not go through, and 1Ppc_NowArT was asserted in itSsem fig. 


EFAULT The address pointed to by sops isn’t accessible 
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EFBIG For some operation, the value of sem_num is less than 0 or greater than or equal to the number of 
semaphores in the set. 

EIDRM The semaphore set was renoved. 

EINTR Sleeping on a wait queue, the process recdved a signal that had to be caught. 

EINVAL The semaphore set doesn’t exist, orsemid isless than 0, ornsops has anon-positive value. 

ENOMEM The sem_f1g Of Some operation asserted sEm_unpdo, and the system does not have ough memory to 
allocate the undo structure. 

ERANGE For some operation, semoptsemvalis is greater than semvux, the implementation-dependent maximum 


value for semval. 


NOTES 


The sem_undo structures of a process aren't inherited by its child on execution of a fork(2) system call. They are instead 
inherited by the substituting process resulting from the execution of the exec(2) system call. 


The following are limits on semaphore set resources affecting asemop Call: 


SEMOPM M aximum number of operations allowed for one semop Call; policy denendent. 
SEMVMX M aximum allowable value for semvai; implementation dependent (32767). 


Theimplementation has no intrinsic limits for the adjust on exit maximum value (semaem), the system-wide maximum 
number of undo structures (semmnu), or the per-process maximum number of undo entries system parameters. 


BUGS 


The systan maintains a per-process sem_undo structure for each semaphore altered by the process with undo requests. T hose 
structures are free at process exit. O ne major cause for unhappiness with the undo mechanism is that it does not fit in with 
the notion of having an atomic set of operations in an array of semaphores. The undo requests for an array and each 
semaphore therein might have been accumulated over many semopt calls. Should the process sleep when exiting, or should all 
undo operations be applied with the rec_nowart flag in effect? Currently those undo operations that go through immediately 
are applied, and those that require a wait are ignored silently. Therefore harmless undo usage is guaranteed with private 
semaphores only. 


SEE ALSO 


ipc(5), semct1(2), semget(2) 
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send, sendto, sendmsg 


send, sendto, sendmsg— Sends a message from a socket 


SYNOPSIS 


#include <sys/types.h> 

#include <sys/socket.h> 

int send(int s, const void *msg,int len, unsigned int flags); 

int sendto(int s, const void *msg, int len, unsigned int flags, 
const struct sockaddr *to, int tolen); 

int sendmsg(int s, const struct msghdr *msg , unsigned int flags); 


DESCRIPTION 
Warning: ThisisaBSD man page As of Linux 0.99.11, sendmsg was not implenented. 


send, sendto, and sendmsg are used to transmit a message to another socket. send may be used only when the socket isin a 
connected state, whereas sendto and sendmsg may be used at any time 


setfsgid 


The address of the target is given byto, with tol en specifying its size. The length of the message is given by | en. If the 
message is too long to pass atomically through the underlying protocol, the error Ewsasi1ze is returned, and the message is not 
transmitted. 


No indication of failure to deliver isimplicit in a send. Locally detected errors are indicated by a return value of -1. 


If no message space is available at the socket to hold the message to be transmitted, send normally blocks, unless the socket 
has been placed in non-blocking 1/O mode. The select(2) call may be used to determine when it is possible to send more 
data. 

Theflags parameter may include one or more of the following: 

#define MSG_O0B 0x1 /* process out-of-band data */ 

#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ 

The flag usc_oos is used to send out-of-band data on sockets that support this notion (for example sock_stReam); the 
underlying protocol must also support out-of-band data. usc_ponTrouTE is usually used only by diagnostic or routing 
programs. 


See recv(2) for adescription of themsghadr structure 


RETURN VALUES 
The call returns the number of characters sent, or -1 if an error occurred. 
ERRORS 
EBADF An invalid descriptor was specified. 
ENOTSOCK Theargument s isnot a socket. 
EFAULT An invalid user space address was specified for a parameter. 
EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made 
thisimpossible 
EWOULDBLOCK The socket is marked non-blocking, and the requested operation would block. 
ENOBUFS The systen was unable to allocate an internal buffer. The operation might succeed when buffers 
become available. 
ENOBUFS The output queue for a network interface was full. T his generally indicates that the interface has 
stopped sending, but it might be caused by transient congestion. 
HISTORY 
T hese function calls appeared in BSD 4.2. 
SEE ALSO 


fent1(2), recv(2), select(2), getsockopt(2), socket(2), write(2) 
BSD Man Page 24 July 1993 


setfsgid 
setfsgid— Sets group identity used for filesystem checks 


SYNOPSIS 


int setfsgid(uid_t fsgid); 


DESCRIPTION 


setfsgid sets the group ID that the Linux kernel uses to check for all accesses to the filesystem. N ormally, the value of f s gi d 
will shadow the value of the effective group ID . In fact, whenever the effective group ID is changed, fsgid will also be 
changed to the new value of the effective group ID. 
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An explicit call to setfsgia is usually only used by programs such as the Linux N FS server that need to change what group 
ID is used for file access without a corresponding change in the real and effective group IDs. A changein thenormal group 
ID s for a program such as the N FS server is a security hole that can expose it to unwanted signals from other group ID s. 


setfsgid will succeed only if the caller is the superuser or if fs gid matches athe the real group ID, effective group ID, saved 
group ID, or the current value of f sgid. 


RETURN VALUE 
On success, the previous value of fs gid isreturned. On error, the current value of fsgid isreturned. 
CONFORMS TO 
setfsgid iS Linux specific. 
BUGS 
No error messages of any kind are returned to the caller. At the very least, EPerm should be returned when the call fails. 
SEE ALSO 
setfsuid(2) 
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setfsuid 

setfsuid— Sets user identity used for filesystem checks 
SYNOPSIS 

int setfsuid(uid_t fsuid); 
DESCRIPTION 


setfsuid sets the user 1D that the Linux kernel uses to check for all accesses to the filesystan. N ormally, the value of f sui d 
will shadow the value of the effective user ID . In fact, whenever the effective user ID is changed, f suid will also be changed 
to the new value of the effective user ID. 


An explicit call to setfsuid is usually used only by programs such as the Linux N FS server that need to change what user ID 
is used for file access without a corresponding change in the real and effective use 1D s. A change in the normal user IDs for a 
program such astheN FS server is a security hole that can exposeit to unwanted signals from other user ID s. 


setfsuid will succeed only if the caller is the superuser or if f suid matches ether the real user 1D, effective user ID , saved user 
ID, or the current value of f suid. 


RETURN VALUE 

On success, the previous value of f sui d is returned. On error, the current value of f suid isreturned. 
CONFORMS TO 

setfsuid is Linux specific. 
BUGS 


No error messages of any kind are returned to the caller. At the very least, EPerm should be returned when the call fails. 


SEE ALSO 


setfsgid(2) 


Linux 1.3.15, 6 August 1995 


setpgid, getpgid, satpgrp, getpgrp 


setgid 
setgid— Sets group identity 
SYNOPSIS 


#include <unistd.h> 
int setgid(gid_t gid); 


DESCRIPTION 


setgid sets the effective group ID of the current process. | f the caller is the superuser, thereal and saved group ID sare also 
set. 


Under Linux, setgid isimplenented like sysv, with savep_tps. T his alows a setgid (other than root) program to drop all its 
group privileges, do some unprivileged work, and then re-engage the original effective group ID in asecuremanner. 


If the user is root or the program is setgid root, special care must be taken. The setgid function checks the effective gid of 
the caller and, if it is that of the superuser, all process-related group ID s are set to gid. After this has occurred, it isimpossible 
for the program to regain root privileges. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 


EPERM The user isnot the superuser, and gi d does not match the effective or saved group ID of the calling process. 


CONFORMS TO 
System V 


SEE ALSO 


getgid(2), setregid(2), setegia(2) 
Linux 1.1.36, 29 July 1994 


setpgid, getpgid, setpgrp, getpgrp 
setpgid, getpgid, setpgrp, getpgrp— Sets/gets process group 


SYNOPSIS 


#include <unistd.h> 

int setpgid(pid_t pid, pid_t pgid); 
pid_t getpgid(pid_t pid); 

int setpgrp(void) ; 

pid_t getpgrp (void) ; 


DESCRIPTION 


setpgid sets the process group ID of the process specified by pid to pgid. If pid isO, the process|D of the current process is 
used. If pgid iSO, the process |D of the process specified by pid is used. 


getpgid returns the process group ID of the process specified by pid. If pid is0, the process!D of the current process is used. 
In theLinux DLL 4.4.1 library, setpgrp simply calls setpgia(0,0). 
getpgrp is equivalent to getpgia(0). 
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Process groups are used for distribution of signals, and by terminals to arbitrate requests for their input; processes that have 
the same process group as the terminal are foreground and may read, whereas others will block with a signal if they attempt 
to read. 

T hese calls are thus used by programs such as csh(1) to create process groupsin implementing job control. The T1ocaParP 
and trocsperp Calls described in termios(4) are used to get/set the process group of the control terminal. 


RETURN VALUE 


On SUCCESS, setpgid and setpgrp return a. On error, -1 iSreturned, and errno is set appropriately. 
getpgid returns a process group on success. On error, -1 iSreturned, and errno is set appropriately. 
getpgrp always returns the current process group. 


ERRORS 
EINVAL pgid iSless than 0. 
EPERM Various permission violations. 
ESRCH pid does not match any process. 
CONFORMS T0 
Thefunctions setpgid and getpgrp conform to POSIX.1. Thefunction setpgrp isfrom BSD 4.2. | haveno information on 
the source of getpgid. 
SEE ALSO 


getuid(2), setsid(2), tcsetpgrp(3), termios(4) 
Linux 1.2.4, 15 April 1995 


setregid, setegid 


setregid, setegid— Sets real and/or effective group |D 


SYNOPSIS 


#include <unistd.h> 

int setregid(gid_t rgid, gid _t egid); 

int setegid(gid_t egid); 
DESCRIPTION 


setregid sésreal and effective group IDs of the current process. U nprivileged users may changethe real group ID to the 
effective group ID, and vice versa. 


Prior to Linux 1.1.38, the saved 1D paradigm, when used with setregid or setegid, was broken. Starting at 1.1.38, it is also 
possible to set the effective group ID from the saved user ID . 


Only the superuser may make other changes. 

Supplying a value of -1 for either the real or effective group ID forces the system to leave that ID unchanged. 

Currently (libc-4.x.x), setegid(egid) isfunctionally equivalent to setregid(-1, egid). 

If the real group ID is changed or the effective group ID is set to a value not equal to the previous real group ID, the saved 
group ID will beset to the new effective group ID. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


sdreuid, scteuid 847 


ERRORS 
EPERM The current process is not the superuser, and changes other than swapping the effective group ID 
with the real group ID , setting one to the value of the other, or setting the effective group ID to the 
value of the saved group ID was specified. 
HISTORY 
The setregid function call appeared in BSD 4.2. 
CONFORMS TO 
BSD 4.3 
SEE ALSO 


getgid(2), setgid(2) 
Linux 1.1.38, 2 August 1994 


Setreuid, seteuid 


setreuid, seteuid— Sets real and / or effective user 1D 


SYNOPSIS 


#include <unistd.h> 

int setreuid(uid_t ruid, uid_t evid); 

int seteuid(uid_t euid); 
DESCRIPTION 


setreuid ses real and effective user ID s of the current process. U nprivileged users may change the real user ID to the 
effective user 1D , and vice versa. 


Prior to Linux 1.1.37, the saved 1D paradigm, when used with setreuid Or seteuid, was broken. 

Starting at 1.1.37, it is also possible to set the effective user ID from the saved user ID. 

Only the superuser may make other changes. 

Supplying a value of -1 for either the real or effective user 1D forces the system to leave that ID unchanged. 
Currently (libc-4.x.x), seteuid(euid) isfunctionally equivalent to setreuid(-1, euid). 


If the real user 1D is changed or the effective user ID is set to a value not equal to the previous real user 1D, the saved user ID 
will be set to the new effective user ID. 


RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 
ERRORS 
EPERM The current process is not the superuser, and changes other than swapping the effective user ID 
with the real user ID , setting one to the value of the othe,, or setting the effective user ID to the 
value of the saved user ID was specified. 
HISTORY 
The setreuid function call appeared in BSD 4.2. 
CONFORMS TO 


BSD 4.3 
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SEE ALSO 


getuid(2), setuid(2) 
Linux 1.1.38, 2 August 1994 


setsid 


setsid— Creates a session and sets the process group | D 


SYNOPSIS 


#include <unistd.h> 
pid_t setsid(void) ; 


DESCRIPTION 


setsid() Creates a new session if the calling process is not a process group leader. T he calling process is the leader of the new 
session, the process group leader of the new process group, and has no controlling tty. The process group ID and session |D 
of the calling process are set to the PID of the calling process. T he calling process will be the only process in this new process 
group and in this new session. 


RETURN VALUE 


It returns the session ID of the calling process. 


ERRORS 


On error, -1 will be returned. The only error that can happen is ererm, which is returned when the process group |D of any 
process equals the PID of the calling process. T hus, in particular, setsid fails if the calling process is already a process group 
leader. 


NOTES 


A process group leader is a process with process group ID equal to its PID. In order to be sure that setsid will succeed, fork, 
and exit, and havethe child do setsid(). 


CONFORMS TO 
POSIX 


SEE ALSO 
setpgid(2), setpgrp(2) 
27 August 1994 


setuid 


setuid— Sets user identity 


SYNOPSIS 


#include <unistd.h> 
int setuid(uid_t uid); 


DESCRIPTION 


setuid sets the effective user |D of the current process. If the caller is the superuser, the real and saved user ID s are also set. 
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Under Linux, setuid is implenented like sysv, with savep_1ps. This allows a setuid (other than root) program to drop all its 
user privileges, do some unprivileged work, and then re-engage the original effective user |D in a secure manner. 


If the user is root or the program is setuid root, special care must be taken. The setuid function checks the effective UID of 
the caller, and, if it isthe superuser, all process-rdated user 1D s are set to ui d. After this has occurred, it isimpossible for the 
program to regain root privileges. 


RETURN VALUE 


On success, o is returned. On error, -1 is returned, and errno is set appropriately. 


ERRORS 


EPERM The user isnot the superuser, and ui d does not match the effective or saved user ID of the calling 
process. 


CONFORMS TO 
System V 


SEE ALSO 


getuid(2), setreuid(2), seteuid(2) 
Linux 1.1.36 29 July 1994 


setup 


setup— Sets up devices and filesystems, mount root filesystem 


SYNOPSIS 


#include <unistd.h> 
syscallQ(int, setup); 
int setup(void) ; 


DESCRIPTION 


setup iScalled oncefrom within 1inux/init/main.c. It calls initialization functions for devices and filesystems configured into 
thekernd and then mounts the root filesystem. 


N 0 user process may Call setup. Any user process, even a process with superuser permission, will receive EPERM. 


RETURN VALUE 

setup always returns -1 for a user process. 
ERRORS 

EPERM Always, for a user process. 
CONFORMS TO 


This function is Linux specific. 
Linux 1.2.9, 3 May1996 


shmctl 


shmet1— Shared memory control 


Part II: System Calls 


SYNOPSIS 


#include <sys/ipc.h> 
#include <sys/shm.h> 
int shmctl(int shmid,int cmd, struct shmid ds *buf ); 


DESCRIPTION 


shmct1() allows the user to recaive information on a shared memory segment, set the owne,, group, and permissions of a 
shared memory segment, or destroy a segment. Theinformation about the segment identified by shmid is returned ina 
shmid_ds structure: 


struct shmid_ds { 

struct ipc_perm shm_perm; /* operation perms */ 

int shm_segsz; /* size of segment (bytes) */ 

time_t shm_atime; /* last attach time */ 

time_t shm_dtime; /* last detach time */ 

time_t shm_ctime; /* last change time */ 

unsigned short shm_cpid; /* pid of creator */ 

unsigned short shm_lpid; /* pid of last operator */ 

short shm_nattch; /* no. of current attaches */ 

/* the following are private */ 

unsigned short shm_npages; /* size of segment (pages) */ 

unsigned long *shm_pages; 

struct shm_desc *attaches; /* descriptors for attaches */ 
}; 


The fields in the member s hm perm can be set: 


struct ipc_perm 


{ 
key_t key; 
ushort uid;/*owner euid and egid */ 
ushort gid; 
ushort cuid; /* creator euid and egid */ 
ushort cgid; 
ushort mode; /* lower 9 bits of access modes */ 
ushort seq; /* sequence number */ 
hs 
The following cmds are available: 
IPC_STAT Used to copy the information about the shared memory segment into the buffer, buf . The user 
must have read access to the shared memory segment. 
IPC_SET Used to apply the changes the user has made to theui d, gid, Or mode mManbers of theshm_ per ms 


fidd. Only the lowest 9 bits of mode are used. Theshm_ ct ime member is also updated. T he user 
must be the owner, the creator, or the superuser. 

IPC_RMID Used to mark the segment as destroyed. It will actually be destroyed after the last detach. (T hat is, 
when theshm nattch member of the associated structureshmid_ds iSzero.)T he user must bethe 
owner, the creator, or the superuser. 


The user must ensure that a segment is eventually destroyed; otherwise the pages that were faulted in will remain in memory 
or swap. 


In addition, the superuser can prevent or allow swapping of ashared memory segment with the following cmds: (Linux only) 


SHM_LOCK Prevents swapping of a shared memory segment. T he user must fault in any pages that are required 
to be present after locking is enabled. 
SHM_UNLOCK Allows the shared memory segment to be swapped out. 


The IPC_INFO, SHM_STAT, aNd SHM_INFO Control calls are used by the ipcs(1) program to provide information on allocated 
resources. In the future, these may be modified as needed or moved to a proc filesystem interface. 


SYSTEM CALLS 
fork() After a fork(), the child inherits the attached shared memory segments. 
exec() After an exec(), all attached shared memory segments are detached (not destroyed). 
exit() On exit(), all attached shared memory segments are detached (not destroyed). 
RETURN VALUE 
0 is returned on success; -1 on error. 
ERRORS 
On error, errno will be set to one of the following: 
EACCESS Returned if 1pc_stat is requested and shm_perm.modes does not allow read access for msqid. 
EFAULT The argument cmd has the value rpc_seT or 1Pc_sTAT, but the address pointed to by buf isn’t 
accessible. 
EINVAL Returned if shmid isnot a valid identifier, or cma isnot a valid command. 
EIDRM Returned if shmid points to arenoved identifier. 
EPERM Returned if 1pc_seT or rPc_RMID is attempted, if theuser is not the creator, the owne,, or the 


superuser, and if the user does not have permission granted to his group or to the world. 


SEE ALSO 


shmget(2), shmop(2) 
Linux 0.99.11, 28 N ovenber 1993 


shmget 


shmget— Allocates a shared memory segment 


SYNOPSIS 


#include <sys/ipc.h> 
#include <sys/shm.h> 
int shmget(key_t key,int size, int shmflg); 


DESCRIPTION 


shmget() returns the identifier of the shared menory segment associated with the value of the argument key. A new shared 
memory segment, with its size equal to the rounding up of size to a multiple of paGe_size, is created if key has the value 
IPC_PRIVATE OF if key isn’t IPC_PRIVATE, if no shared memory segment is associated to key, and if 1pc_cReAT is asserted in 
shmfg (that is, shmflg& IPC_CREAT isn’t 0). The presence in shmflg is composed of 


IPC_CREAT Creates anew segment. If this flag is not used, shmget() will find the segment associated with key, 
check to see if the user has permission to receive the shmid associated with the segment, and ensure 
the segment is not marked for destruction. 

IPC_EXCL Used with rpc_creat to ensure failure if the segment exists. 


mode_flags (lowest 9 bits) Specifies the permissions granted to the owner, group, and world. Presently, the 
execute permissions are not used by the system. 


If anew segment is created, the access permissions from shmfig are copied into the shm_perm member of the shmid_ds 
structure that defines the segment. Following is the shmid_ds structure 
struct shmid_ds { 


struct ipc_perm shm_perm; /* operation perms */ 
int shm_segsz; /* size of segment (bytes) */ 
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time_t shm_atime; /* last attach time */ 
time_t shm_dtime; /* last detach time */ 
time_t shm_ctime; /* last change time */ 
unsigned short shm_cpid; /* pid of creator */ 
unsigned short shm_lpid; /* pid of last operator */ 
short shm_nattch; /* no. of current attaches */ 

}; 


struct ipc_perm 

{ 
key_t key; 
ushort uid; /* owner euid and egid */ 
ushort gid; 
ushort cuid; /* creator euid and egid */ 
ushort cgid; 
ushort mode; /* lower 9 bits of shmflg */ 
ushort seq; /* sequence number */ 

hs 


Furthermore while creating, the system call initializes the systan shared menory segment data structure shmid_ds as follows: 





HM sshm_perm.cuid and shm_perm.uid are set to the effective user 1D of the calling process. 
HM sshm_perm.cgid and shm_perm.gid are sé to the effective group ID of the calling process. 
M@ Thelowest-order 9 bits of shm_perm.mode are set to the lowest-order 9 bit of shmfig. 
Ms shm_segsz isse@ to the value of size. 
HM sshm_lpid, shm_nattch, shm_atime, aNd shm_dtime are set to a. 
Ml sshm_ctime isset to the current time. 
If the shared memory segment already exists, the access permissions are verified, and a check is made to see if it ismarked for 
destruction. 
SYSTEM CALLS 
fork() After a fork(), the child inherits the attached shared memory segments. 
exec() After an exec(), all attached shared memory segments are detached (not destroyed). 
exit() On exit(), all attached shared memory segments are detached (not destroyed). 
RETURN VALUE 
A valid segment identifier, shmia, is returned on success, -1 on error. 
ERRORS 
On failure, errno is set to one of the following: 
EINVAL Returned if sHwmrn is greater than size, if size is greater than sHmmax, or if size is greater than the 
size of the segment. 
EEXIST Returned if 1pc_cREAT | IPC_EXCL was specified and the segment exists. 
EIDRM Returned if the segment is marked as destroyed or was removed. 
ENOSPC Returned if all possible shared memory ID s havebeen taken (shunt) or if allocating a segment of 
the requested size would cause the system to exceed the system-wide limit on shared memory 
(SHMALL). 
ENOENT Returned if no segment exists for the given key, and IPC_CREAT was not specified. 
EACCES Returned if the user does not have permission to access the shared memory segment. 
ENOMEM Returned if no memory could be allocated for segment overhead. 


NOTES 


IPC_PRIVATE isn’t a flag fidd but a key_t type If this special value is used for key, the system call ignores everything but the 
lowest order 9 bits of shmf!g and creates anew shared memory segment (on success). 


The following are limits on shared memory segment resources affecting a shmget call: 


SHMALL System-wide maximum of shared memory pages; policy dependent. 

SHNMAX Maximum size in bytes, for a shared memory segment; implenentation dependent (currently 
4M B). 

SHNMIN Minimum size, in bytes, for a shared memory segment; implementation dependent (currently 1 
byte, although pace_size is the effective minimum size). 

SHMIMNI System-wide maximum number of shared memory segments; implementation dependent (currently 
4096). 

Theimplementation has no specific limits for the per-process maximum number of shared menory segments (SHMSEG). 

BUGS 


Use of 1pc_PrivaTe does not inhibit other processes’ access to the allocated shared memory segment. 


As for the files, there is currently no intrinsic way for a process to ensure exclusive access to a shared memory segment. 
Asserting both 1pc_crReaT and IPC_EXCL in shmflg only ensures (on success) that anew shared memory segment will be 
created; it doesn’t imply exclusive access to the segment. 


SEE ALSO 
ftok(3), ipc(5), shmct1(2), shmat(2), shmdt(2) 
Linux 0.99.11, 28 N ovember 1993 


shmop 


shmop— Shared memory operations 


SYNOPSIS 


#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/shm.h> 

char *shmat ( int shmid, char *shmaddr, int shmflg ); 
int shmdt ( char *shmaddr ); 


DESCRIPTION 


The function shmat attaches the shared memory segment identified by shmid to the data segment of the calling process. The 
attaching address is specified by shmadar with one of the following criteria: 


If shmadar ise, the system tries to find an unmapped region in the range 1-1.5GB, starting from the upper value and 
coming down from there 

Mf shmaddr isn’t 0 and SHM_RND is asserted in shmf1g, the attach occurs at the address equal to the rounding down of 
shmaddr to a multiple of sHwLBa. O therwise, shmaddr must be a page-aligned address at which theattach occurs. 


If SHM RDONLY is asserted in shmf!g, the segment is attached for reading, and the process must have read access permissions to 
the segment. O therwise the segment is attached for read and write, and the process must have read and write access 
permissions to the segment. Thereis no notion of awrite-only shared memory segment. 


The brk value of the calling process is not altered by the attach. T he segment will automatically be detached at process exit. 
The same segment may be attached as aread and as a read-write segment, more than once, in the process's address space. 
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On asuccessful shmat call, the system updates the members of the structure shmid_ds associated to the shared memory 
segment as follows: 


Ms shm_atime isset to the current time 
Ms shm_lpid is set to the process! D of the calling process. 
HM sshm_nattch isincremented by 1. 


N ote that the attachment will also succeed if the shared memory segment is marked to be ddeted. 


The function shmdt detaches from the calling process's data segment the shared memory segment located at the address 
specified by shmaddr. The detaching shared memory segment must be one among the currently attached ones (to the 
process's address space) with shmaddr equal to the value returned by its attaching shat call. 


On asuccessful shmdt call, the system updates the members of the structure shmid_ds associated to the shared memory 
segment as follows: 


MI sshm_dtime isset to the current time. 
HM sshm_lpid is set to the process|D of the calling process. 
HM sshm_nattch is decremented by 1. If it becomes 0 and the segment is marked for deletion, the segment is ddeted. 


The occupied region in theuser space of the calling process is unmapped. 


SYSTEM CALLS 
fork() After a fork(), the child inherits the attached shared memory segments. 
exec() After an exec(), all attached shared manory segments are detached (not destroyed). 
exit() On exit(), all attached shared memory segments are detached (not destroyed). 
RETURN VALUE 


On afailure, both functions return -1 with errno indicating the error; otherwise, shmat returns the address of the attached 
shared memory segment, and shmdt returns 0. 


ERRORS 


When shmat fails, at return errno will be set to one of the following values: 


EACCES The calling process has no access permissions for the requested attach type 

EINVAL Invalid shmid value, unaligned (that is, not page aligned and sHw_RNp was not specified) or invalid 
shmaddr value, or failing attach at brk. 

ENOMEM Could not allocate menory for the descriptor or for the page tables. 


The function shmdt can fail only if thereis no shared memory segment attached at shmaddr ; in such a case errno will be set to 
EINVAL at return. 


NOTES 
On executing a fork(2) system call, the child inherits all the attached shared memory segments. 


The shared memory segments attached to a process executing anexec(2) system call will not be attached to the resulting 
process. 


The following isa system parameter affecting a shmat system call: 


SHMLBA Segments low-boundary address multiple. M ust be page aligned. For the current implenentation, 
the SHMBLA Value iS PAGE_SIZE. 


Theimplementation has no intrinsic limit to the per- process maximum number of shared memory segments (SHMSEG) 
SEE ALSO 
ipce(5), shmct1(2), shmget(2) 
Linux 0.99.13, 28 N ovenber 1993 
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shutdown 


shutdown— Shuts down part of a full-duplex connection 


SYNOPSIS 


#include <sys/socket.h> 
int shutdown(int s,int how); 


DESCRIPTION 


The shutdown call causes all or part of a full-duplex connection on the socket associated with s to be shut down. If how ise, 
further receives will be disallowed. If how is1, further sends will be disallowed. If how is2, further sends and receives will be 
disallowed. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 
ERRORS 
EBADF s isnot a valid descriptor. 
ENOTSOCK s iSafile, not a socket. 
ENOTCONN The specified socket is not connected. 
HISTORY 
The shutdown function call appeared in BSD 4.2. 
SEE ALSO 


connect(2), socket(2) 
BSD Man Page 24 July 1993 


Sigact1on, sigprocmask, Sigpending, sigsuspend 


sigaction, sigprocmask, sigpending, sigsuspend— PO SIX signal-handling functions. 


SYNOPSIS 


#include <signal.h> 

int sigaction(int signum, const struct sigaction *act, struct sigaction *oldact); 
int sigprocmask(int how, const sigset_t *set, sigset_t *oldset ); 

int sigpending(sigset_t *set); 

int sigsuspend(const sigset_t *mask); 


DESCRIPTION 
The sigaction system call is used to change the action taken by aprocess on receipt of a specific signal. 


si gnum Specifies the signal and can be any valid signal except s1GkILL and stcsTop. 


If act isnon-null, the new action for signal signum isinstalled from act. If ol dact isnon-null, the previous action is saved in 
oldact. 
The sigaction structure is defined as 
struct sigaction { 
void (*sa_handler) (int); 


sigset_t sa_mask; 
int sa_flags; 
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void (*sa_restorer) (void); 


} 


sa_handler specifies the action to be associated with si gnum and can be ste_prL for the default action, sta_1en to ignore this 
signal, or apointer to a signal-handling function. 


sa_mask gives a mask of signals that should be blocked during execution of the signal handler. In addition, thesignal that 
triggered thehandler will be blocked unless the sa_NODEFER Or SA_NoMASK flag is used. 


sa_flags specifies a set of flags that modify the behavior of the signal-handling process. It is formed by the bitwise O R of zero 
or more of the following: 


SA_NOCLDSTOP If signumiSSt@cHLp, do not recave notification when child processes stop (that is, when 
child processes receive one of SIGSTOP, SIGTSTP, SIGTTIN, OF SIGTTOU). 

SA_ONESHOT OF SA_RESETHAND Restores the signal action to the default state once the signal handler has bem called. 
(This is the default behavior of the signal(2) system call.) 

SA_RESTART Provides behavior compatible with BSD signal sanantics by making certain system calls 
restartable across signals. 

SA_NOMASK Or SA_NODEFER Does not prevent the signal from being received from within its own signal handler. 


Thesa_restorer element is obsolete and should not be used. 


The sigprocmask Call is used to change the list of currently blocked signals. T he behavior of the call is dependent on the value 
of how, as follows: 


SIG_BLOCK The set of blocked signals is the union of the current set and theset argument. 

SIG_UNBLOCK The signals inset are removed from the current set of blocked signals. It is legal to 
attempt to unblock a signal that isnot blocked. 

SIG_SETMASK The set of blocked signals is set to the argument set. 


If oldset iSnon-null, the previous value of the signal mask is stored in 01 dset. 


The sigpending call allows the examination of pending signals (those that have been raised while blocked). T he signal mask 
of pending signals is stored inset. 


The sigsuspend call temporarily replaces the signal mask for the process with that given by mask and then suspends the 
process until a signal is recived. 


RETURN VALUES 
sigaction, sigprocmask, sigpending, and sigsuspend return 0 ON SUCCESS and -1 on error. 
ERRORS 
EINVAL An invalid signal was specified. T his will also be generated if an attempt is made to 
change the action for stGkILL or stastop, which cannot be caught. 
EFAULT act, oldact, set, Oroldset pointsto memory that is not a valid part of the process 
address space. 
EINTR System call was interrupted. 
NOTES 


It isnot possibleto block steKILL or stasTop with the sigprocmask call. Attemptsto do so will be silently ignored. 
Setting SIGCHLD to s1q_IGn provides automatic reaping of child processes. 

ThePO SIX spec only defines sa_nocLostop. U se of other sa flags is non- portable. 

T he sA_RESETHAND flag is compatible with the SV R4 flag of the same name. 
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The sa_noperer flag is compatible with the SV R4 flag of the same name under Kernels 1.3.9 and newer. On older kernels, the 
Linux implementation will allow the receipt of any signal, not just the one you are installing (effectively overriding any 
sa_mask settings). 


The Sa_RESETHAND and SA_NODEFER namesfor SVR4 compatibility are present only in library versions 3.0.9 and greater. 


sigaction can be called with anull second argument to query the current signal handler. It can also be used to check whether 
a given signal is valid for the current machine by calling it with null second and third arguments. 


Se sigsetops(3) for details on manipulating signal sets. 


CONFORMS TO 
POSIX, SVR4 


SEE ALSO 
kill(1), kil1(2), killpg(2), pause(2), raise(3), siginterrupt(3), signal(2), signal(7), sigse-tops(3), sigvec(2) 
Linux 1.3, 24 August 1995 


signal 


signal— AN SI C signal handling 
SYNOPSIS 


#include <signal.h> 
void (*signal(int signum,void (*handler)(int))) (int); 
DESCRIPTION 


The signal system call installs a new signal handler for the signal with number si gnum. The signal handler is set to handler, 
which can be a user-specified function or one of the following: 


SIG_IGN Ignores the signal. 
SIG_DFL Resets the signal to its default behavior. 


Theinteger argument that is handed over to the signal-handling routine is the sgnal numbe. T his makesit possible to use 
onesignal handler for several signals. 


RETURN VALUE 


signal returns the previous value of the signal handler, or sta_err on error. 


NOTES 
Signal handlers cannot be set for sIGKILL or SIGSTOP. 


Unlike on BSD systems, signals under Linux are reset to their default behavior when raised. H owever, if you include <bsd/ 
signal.h> instead of <signal.h>, signal is redefined aS_bsd_signal, and signal hasthe BSD semantics. Both versions of 
signal are library routines built on top of sigaction(2). 





If you're confused by the prototype at the top of thisman page, it may help to see it separated out like this: 

typedef void (*sighandler_t) (int); 

sighandler_t signal(int signum, sighandler_t handler); 

According to PO SIX, the behavior of a process is undefined after it ignores asIGFPE, SIGILL, or sIGseGv signal that was not 


generated by the ki1l() or raise() function. Integer division by 0 has undefined result. O n some architectures it will 
generate a sterre signal. Ignoring this signal might lead to an endless loop. 
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CONFORMS TO 
ANSIC 


SEE ALSO 
kill(1), kil1(2), killpg(2), pause(2), raise(3), sigaction(2), signal(7), sigsetops(3), sigvec(2), alarm(2) 
Linux 2.0, 21 July 1996 


Sigblock, siggetmask, Sigsetmask, Sigmask 
sigblock, siggetmask, sigsetmask, sigmask— M anipulate the signal mask 


SYNOPSIS 


#include <signal.h> 

int sigblock(int mask); 
int siggetmask(void); 

int sigsetmask(int mask); 
int sigmask(int signum); 


DESCRIPTION 
This interface is made obsolete by sigprocmask(2). 
The sigblock system call adds the signals specified in mask to the set of signals currently being blocked from delivery. 


The sigsetmask system call replaces the set of blocked signals totally with a new set specified in mask. Signals are blocked if 
the corresponding bitin mask isal. 


The current set of blocked signals can be obtained using siggetmask. 

The sigmask macro is provided to construct the mask for a given si gnum. 
RETURN VALUES 

siggetmask returns the current set of masked signals. 

sigsetmask and sigblock return the previous set of masked signals. 


NOTES 
Prototypes for these functions are only available if __use_Bsp is defined before <signal.h> is included. 
It isnot possibleto block stek1LL or stastop— this restriction is silently imposed by the system. 


HISTORY 
These function calls appeared in BSD 4.3 and are deprecated. 


SEE ALSO 
kill(2), sigoprocmask(2), signal(7) 
Linux 1,3, 31 August 1995 


Sigpause 


sigpause— Atomically releases blocked signals and waits for interrupt 


ggreturn 


SYNOPSIS 


#include <signal.h> 
int sigpause(int sigmask ); 


DESCRIPTION 


This interface is made obsolete by sigsuspend(2). 


sigpause assignSsigmask to the set of masked signals and then waits for a signal to arrive on return, the set of masked signals 
is restored. 


sigmask is usually @ to indicate that no signals are to be blocked. sigpause always terminates by being interrupted, returning 
-1 with errno set to EINTR. 


HISTORY 
The sigpause function call appeared in BSD 4.3 and is deprecated. 


SEE ALSO 


sigsuspend(2), kil1(2), sigaction(2), sigprocmask(2), sigblock(2), sigvec(2) 
Linux 1.3, 24 July 1993 


sigreturn 


sigreturn— Returns from the signal handler and cleans up the stack frame 


SYNOPSIS 


int sigreturn(unsigned long _ unused); 


DESCRIPTION 


When the Linux kernel creates the stack frame for a signal handle, a call to sigreturn isinserted into the stack frame so that 
the signal handler will call sigreturn upon return. T his inserted call to sigreturn cleans up the stack so that the process can 
restart from where it was interrupted by the signal. 


RETURN VALUE 


sigreturn neve’ returns. 


WARNING 


The sigreturn Call is used by the kernel to implement signal handlers. It should never be called directly. Better yet, the 
specific use of the unused argument varies depending on the architecture 


CONFORMS TO 


sigreturn is specific to Linux. 


FILES 


/usr/src/linux/arch/i386/kernel/signal.c 
/usr/src/linux/arch/alpha/kernel/entry.S 


SEE ALSO 
kill(2), signal(2), signal(7) 
Linux 1.3.20, 21 August 1995 
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sigvec 
sigvec— BSD software signal facilities 


SYNOPSIS 


#include <bsd/signal.h> 
int sigvec(int sig, struct sigvec *vec, struct sigvec *ovec); 


DESCRIPTION 

This interface is made obsolete by sigaction(2). 

Under Linux, sigvec iS#defined to sigaction, and provides at best arough approximation of the BSD sigvec interface. 
SEE ALSO 


sigaction(2), signal(2) 
Linux 1.3 31 August 1995 


socket 


socket— Creates an endpoint for communication 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/socket.h> 
int socket(int domain,inttype, int protocol ); 


DESCRIPTION 
socket creates an endpoint for communication and returns a descriptor. 


The domain parameter specifies a communications domain within which communication will take place this selects the 
protocol family that should be used. T hese families are defined in the include file sys/socket.h. T he currently understood 


formats are 

AF_UNIX UNIX internal protocols 

AF_INET ARPA Internet protocols 

AF_ISO ISO protocols 

AF_NS Xerox N ework Systems protocols 
AF_IMPLINK IM P host at IM P link layer 


The socket has the indicated type, which specifies the sanantics of communication. The currently defined types are 


SOCK_STREAM 
SOCK_DGRAM 
SOCK_RAW 
SOCK_SEQPACKET 
SOCK_RDM 


A sock_sTREAM type provides sequenced, rdiable, two-way connection- based byte streams. An out-of-band data transmission 
mechanism may be supported. A sock_peram socket supports datagrams (connectionless, unrdiable messages of a fixed, 
typically small, maximum length). A sock_sE@PACKET socket may provide a sequenced, reliable, two-way connection- based 
data transmission path for datagrams of fixed maximum length; a consumer might be required to read an entire packet with 
each read system call. This facility is protocol specific, and presently isimplemented only for pF_ns. sock_RAW sockets provide 


access to internal network protocols and interfaces. T he types sock_raw, which is available only to the superuser, and 
sock_Rpm, which is planned but not yet implemented, are not described here. 


Theprotocol specifies a particular protocol to be used with the socket. N ormally only a single protocol exists to support a 
particular socket type within a given protocol family. H owever, it is possiblethat many protocols may exist, in which casea 
particular protocol must be specified in this manne. The protocol number to use is particular to the communication domain 
in which communication is to take place; see protocols(5). 


Sockets of type sock_sTREAM are full-duplex byte streams, similar to pipes. A stream socket must bein a connected state before 
any data can be sent or received on it. A connection to another socket is created with a connect(2) call. Once connected, data 
may be transferred using read(2) and write(2) calls or some variant of the sena(2) and recv(2) calls. When a session has been 
completed, aclose(2) may be performed. O ut-of-band data can also be transmitted as described in send(2) and received as 
described in recv(2). 


The communications protocols used to implement a sock_sTrREAM ensure that data is not lost or duplicated. If a piece of data 
for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time the 
connection is considered broken, and calls will indicate an error with -1 returns and with Etrmepour as the specific codein the 
global variable errno. The protocols optionally keep sockets warm by forcing transmissions roughly every minute in the 
absence of other activity. An error isthen indicated if no response can be dicited on an otherwise idle connection for a 
extended period (for example, 5 minutes). A steppe signal is raised if a process sends on a broken stream; this causes naive 
processes, which do not handle the signal, to exit. 


SOCK_SEQPACKET sockets enploy the same systam calls as sock_sTReam sockets, The only difference is that read(2) calls will 
return only the anount of data requested, and any that is remaining in the arriving packet will be discarded. 


SOCK_DGRAM and sock_RAw sockets allow the sending of datagrams to correspondents named in send(2) calls. D atagrams are 
generally received with recvfrom(2), which returns the next datagram with its return address. 





An fent1(2) call can be used to specify a process group to recave a sicure signal when the out-of-band data arrives. It can 
also nnable non-blocking 1/O and asynchronous notification of I/O events viastazo. 


The operation of sockets is controlled by socket-level options. T hese options are defined in the file sys/socket.h. 
setsockopt(2) and getsockopt(2) and are used to set and get options, respectively. 


RETURN VALUES 
A -1 isreturned if an error occurs; otherwise, the return value is a descriptor referencing the socket. 
ERRORS 
EPROTONOSUPPORT The protocol type or the specified protocol isnot supported within this domain. 
EMFILE The per-process descriptor table is full. 
ENFILE The system file table is full. 
EACCESS Permission to create a socket of the specified type and/or protocol is denied. 
ENOBUFS Insufficient buffer space is available. The socket cannot be created until sufficient resources are 
freed. 
HISTORY 
The socket function call appeared in BSD 4.2. 
SEE ALSO 


accept(2), bind(2), connect(2), getprotoent(3), getsockname(2), getsockopt(2), ioct1(2), listen(2), read(2), recv(2), 
select(2), send(2), shutdown(2), socketpair(2), write(2) 


“An Introductory 4.3 BSD Interprocess Communication T utorial” is reprinted in UNIX Programmer's Supplementary 
Documents Volume 1 


“BSD Interprocess Communication T utorial” is reprinted in UNIX Programmer's Supplementary D ocuments Volume 1 
BSD Man Page 24 July 1993 
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socketcall 


socketcall— Socket system calls 


SYNOPSIS 


int socketcall(int call , unsigned long *args); 


DESCRIPTION 
socketcall isacommon kernd entry point for the socket system calls. cal! determines which socket function to invoke. args 
points to a block containing the actual arguments, which are passed through to the appropriate call. 


User programs should call the appropriate functions by their usual names. O nly standard library implementors and kernd 
hackers need to know about socketcall. 


SEE ALSO 


accept(2), bind(2), connect(2), getpeername(2), getsockname(2), getsockopt(2), listen(2), recv(2), recvfrom(2), send(2), 
sendto(2), setsockopt(2), shutdown(2), socket(2), socketpair(2) 


Linux 1.2.4, 15 April 1995 


socketpair 


socketpair— Creates a pair of connected sockets 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/socket.h> 
int socketpair(int d, int type, int protocol , int sv[2]); 


DESCRIPTION 


The call creates an unnamed pair of connected sockets in the specified domain d, of the specified t ype, and using the 
optionally specified protocol! . T he descriptors used in referencing the new sockets are returned in sv [a] and sv(1]. Thetwo 
sockets are indistinguishable. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 
ERRORS 
EMFILE Too many descriptors are in use by this process. 
EAFNOSUPPORT The specified address family is not supported on this machine 
EPROTONOSUPPORT The specified protocol is not supported on this machine 
EOPNOSUPPORT The specified protocol does not support creation of socket pairs. 
EFAULT The address sv does not specify a valid part of the process's address space. 
HISTORY 
The socketpair function call appeared in BSD 4.2. 
BUGS 


This call is currently implemented only for the UN IX domain. 


dat, fat, Isat 


SEE ALSO 
read(2), write(2), pipe(2) 
BSD Man Page 24 July 1993 


Stat, fstat, lstat 


stat, fstat, lstat— Get file status 


SYNOPSIS 


#include <sys/stat.h> 

#include <unistd.h> 

int stat(const char *file_name,struct stat *buf); 
int fstat(int filedes ,struct stat *buf ); 

int lstat(const char *file_name, struct stat *buf); 


DESCRIPTION 


T hese functions return information about the specified file. You do not need any access rights to the file to get this 
information, but you need search rights to all directories named in the path leading to the file. 


stat stats the file pointed to byfile_ name and fillsin buf. 
1stat iSidentical to stat, except that the link itself is stated, not the file that is obtained by tracing the links. 


fstat isidentical to stat, except that the open file pointed to by filedes (as returned by open(2)) is stated in place of 
file name. 


They all return a stat structure, which is declared as follows: 


struct stat 





{ 
dev_t st_dev; /* device */ 
ino_t st_ino; /* inode */ 
umode_t st_mode; /*protection */ 
nlink_t st_nlink; /* number of hard links */ 
uid_t st_uid; /* user ID of owner */ 
gid_t st_gid; /* group ID of owner */ 
dev_t st_rdev; /* device type (if inode device) */ 
off_t st size; /* total size, in bytes */ 
unsigned long st_blksize; /* blocksize for filesystem I/O */ 
unsigned long st_blocks ; /* number of blocks allocated */ 
time_t st_atime; /* time of last access */ 
time_t st_mtime; /* time of last modification */ 
time_t st_ctime; /* time of last change */ 


hs 
N ote that st blocks may not always bein terms of blocks of sizest_biksize, and thatst_biksize may instead providea 
notion of the “preferred” block size for efficient filesystem 1/0. 


N ot all the Linux filesystems implement all the time fields. Traditionally, st_atime ischanged by mknod(2), utime(2), read(2), 
write(2), and truncate(2). 


Traditionally, st_mtime is changed by mknod(2), utime(2), and write(2). st_mtime isnot changed for changes in owner, group, 
hard link count, or mode. 


Traditionally, st _ctime is changed by writing or by setting inode information (that is, owner, group, link count, mode, and 
so on). 
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The following macros are defined to check the file type: 


S_ISLNK(m) Isit a symbolic link? 
S_ISREG(m) Isit aregular file? 

S$ _ISDIR(m) Isit a directory? 
$_ISCHR(m) Isit acharacter device? 
S_ISBLK(m) Isit a block device? 
S_ISFIFO(m) Is it fifo? 

$ _ISSOCK(m) Isit asocket? 





The following flags are defined for thest_mode fidd: 


S_IFMT 00170000 Bitmask for the file type bitfields 

S_IFSOCK 0140000 Socket 

S_IFLNK 0120000 Symbolic link 

S_IFREG 0100000 Regular file 

$_IFBLK 0060000 Block device 

S_IFDIR 0040000 D irectory 

S_IFCHR 0020000 Character device 

S_IFIFO 0010000 Fifo 

$_ISUID 0004000 Set UID bit 

S_ISGID 0002000 Set GID bit 

S_ISVTX 0001000 Sticky bit 

S_IRWXU 00700 U ser (file owne’) has read, write, and execute permission 

S$ _IRUSR (S_IREAD) 00400 U ser has read permission 

S_IwusR (S_IWRITE) 00200 User has write permission 

S$ _IXUSR ($_IEXEC) 00100 U ser has execute permission 

S_IRWXG 00070 Group has read, write, and execute permission 

$_IRGRP 00040 Group has read permission 

S_IWGRP 00020 Group has write permission 

S_IXGRP 00010 Group has execute permission 

S_IRWXO 00007 others have read, write, and execute permission 

S_IROTH 00004 O thers have read permission 

S_IWOTH 00002 O thers have write permission 

$_IXOTH 00001 O thers have execute permission 
RETURN VALUE 

On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 
ERRORS 

EBADF filedes isbad. 

ENOENT File does not exist. 
CONFORMS TO 

SVID (not istat()), AT&T (not istat()), POSIX (not istat()), X/OPEN (not istat()), BSD 4.3 
SEE ALSO 


chmod(2), chown(2), readlink(2), utime(2) 
Linux 1.1.75, 1 January 1995 


Statfs, fstatfs 


statfs, fstatfs— Get filesystem statistics 


SYNOPSIS 


#include <sys/vfs.h> 
int statfs(const char *path, struct statfs *buf); 
int fstatfs(int fd, struct statfs *buf); 


DESCRIPTION 


gatfs fstatfs 


statfs returns information about a mounted filesysten. path isthe pathname of any file within the mounted filesystem. buf 
isapointer to astatfs structure defined as follows: 


struct statfs { 





ong f_type; [= 
ong f_bsize; L® 
ong f_blocks; [* 
ong f_bfree; i 
ong f_bavail; 1 
ong f_files; /* 
ong f_ffree; i 
sid t f_fsid; |* 
ong f_namelen; [* 
ong f_spare[6]; [e 

} 

Filesystem types: 


inux/ext2_fs.h: 
inux/ext2_fs.h: 
inux/ext_fs.h: 
inux/iso_fs.h: 
inux/minix_fs.h: 
inux/minix_fs.h: 
inux/minix_fs.h: 
inux/msdos_fs.h: 
inux/nfs_fs.h: 
inux/proc_fs.h: 
inux/xia_fs.h: 





type of filesystem (see below) */ 
optimal transfer block size */ 

total data blocks in filesystem */ 
free blocks in fs */ 

free blocks avail to non-superuser */ 
total file nodes in filesystem */ 
free file nodes in fs */ 

filesystem id */ 

maximum length of filenames */ 

spare for later */ 








EXT2_OLD_SUPER_MAGIC OxEF51 
EXT2_SUPER_MAGIC OxEF53 
EXT_SUPER_MAGIC 0x137D 


ISOFS_SUPER | 
MINIX_SUPER_| 
MINIX_SUPER_| 


MAGIC Ox9660 
MAGIC 0x137F /* orig. minix */ 
MAGIC2 Ox138F /* 30 char minix */ 


NEW_MINIX_SUPER_MAGIC @x2468 /* minix V2 */ 


MSDOS_SUPER_| 


MAGIC 0x4d44 


NFS_SUPER_MAGIC @x6969 
PROC_SUPER_MAGIC ox9tad 


XIAFS_SUPER_| 


MAGIC @x012FD16D 


Fields that are undefined for a particular filesystem are set to -1. fstatfs returns the same information about an open file 
referenced by descriptor fd. 


RETURN VALUE 


On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 


ERRORS 
For statfs 
ENOTDIR 
EINVAL 
ENAMETOOLONG 


ENOENT 
EACCES 
ELOOP 


A component of the path prefix of path isnot a directory. 
path contains a character with the high-order bit set. 


Thelength of acomponent of pat nh exceeds 255 characters, or the length of path exceeds 1,023 
characters. 


The file referred to by path does not exist. 
Search permission is denied for acomponent of the path prefix of path. 
Too many symbolic links were encountered in translating path. 
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EFAULT buf Of path points to an invalid address. 
EIO An I/O error occurred while reading from or writing to the filesysten. 


For fstatfs: 


EBADF fd isnot a valid open file descriptor. 

EFAULT buf points to an invalid address. 

EIO An 1/0 error occurred while reading from or writing to the filesysten. 
SEE ALSO 

stat(2) 


Linux 0.99.11, 24 July 1993 


stime 


stime— Set time 


SYNOPSIS 


#include <time.h> 
int stime(time_t *t); 


DESCRIPTION 


stime sets the system's idea of the time and date time, pointed to byt, is measured in seconds from 00:00:00 GMT January 
1, 1970. stime() may only be executed by the superuser. 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 


EPERM The caller is not the superuser. 


CONFORMS TO 
SVID, AT&T, X/OPEN 


SEE ALSO 
date(1) 
Linux 0.99.11, 24 July 1993 


swapon, swapotf 


swapon, swapoff— Start/stop swapping to file/ device 


SYNOPSIS 


#include <unistd.h> 

#include <linux/swap.h> 

int swapon(const char *path, int swapflags); 
int swapoff(const char *path); 
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DESCRIPTION 


swapon sets the swap area to the file or block device specified by path. swapoft stops swapping to the file or block device 
specified by path. 


swapon takeS aswapflags argument. If swapflags has the swap_FLAG_PREFER bit turned on, the new swap area will have a higher 
priority than default. The priority is encoded as (prio << SWAP_FLAG_PRIO SHIFT) & SWAP_FLAG PRIO_ MASK. T hese functions 
may only be used by the superuser. 


PRIORITY 


Each swap area has a priority, athe: high or low. The default priority is low. Within the low-priority areas, newer areas are of 
even lower priority than older areas. 


All priorities set with swapflags arehigh priority, higher than the default. T hey may have any non-negative value chosen by 
the caller. Higher numbers mean higher priority. 


Swap pages are allocated from areas in priority order, highest priority first. For areas with different priorities, a higher- 
priority area is exhausted before using a lower-priority area. |f two or more areas have the same priority, and that is the 
highest priority available, pages are allocated on a round-robin basis between then. 


As of Linux 1.3.6, the kernel usually follows these rules, but there are exceptions. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 
ERRORS 
M any other errors besides the following can occur if path isnot valid: 
EPERM The user isnot the superuser, or more than max_swaPFILes (defined to be 8 in Linux 1.3.6) arein 
use. 
EINVAL Returned if path exists, but isneither a regular path nor a block device. 
ENOENT Returned if path does not exist. 
ENOMEM Returned if there is insufficient memory to start swapping. 
CONFORMS TO 
T hese functions are Linux specific. 
NOTES 
The partition or path must be prepared with mkswap(8). 
HISTORY 
The second (swapflags) argument was introduced in Linux 1.3.2. 
SEE ALSO 


mkswap(8), swapon(8), swapotf(8) 
Linux 1.3.6, 22 July 1995 


symlink 


symlink— M akes anew namefor afile 


868 Part II: System Calls 


SYNOPSIS 


#include <unistd.h> 
int symlink(const char *oldpath, const char *newpath); 


DESCRIPTION 
symlink creates a symbolic link named o! dpath that contains newpath. 


Symbolic links are interpreted at runtime, as if the contents of the link were substituted into the path being followed to find 
a file or directory. 


Symbolic links may contain .. path components that (if used at the start of the link) refer to the parent directories of the one 
in which the link resides. 


A symbolic link (also known as a soft link) can point to an existing file or to anonexistent one the latter case is known asa 
dangling link. 


The permissions of a symbolic link are irrelevant; the ownership isignored when following the link, but is checked when 
removal or renaming of the link is requested and the link isin a directory with the sticky bit set. 


If newpath exists, it will not be overwritten. 


RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 
ERRORS 
EPERM The filesystem containing pathname doesnot support the creation of symbolic links. 
EFAULT oldpath Or newpath points outside your accessible address space. 
EACCES W rite access to the directory containing newpath isnot allowed for the process's effective UID, or 
oneof the directories in newpath did not allow search (execute) permission. 
ENAMETOOLONG oldpath Ofnewpath Was too long. 
ENOENT A directory component in newpath does not exist or isa dangling symbolic link, oro! dpath isthe 
empty string. 
ENOTDIR A component used as a directory in newpath isnot, in fact, adirectory. 
ENOMEM Insufficient kernel memory was available. 
EROFS Thefileis on a read-only filesystem. 
EEXIST newpath already exists. 
ELOOP newpath Contains a reference to a circular symbolic link— that is, a symbolic link whose expansion 
contains a reference to itself. 
ENOSPC The device containing the file has no room for the new directory entry. 
NOTES 


No checking of ol dpath isdone 


D eleting the name referred to by a symlink will actually delete the file (unless it also has other hard links). If this behavior is 
not desired, use link. 


CONFORMS TO 
SVID, AT&T, POSIX, BSD 4.3 


BUGS 


Se open(2) regarding multiple files with the samename, and NFS. 
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SEE ALSO 
link(2), unlink(2), rename(2), open(2), 1stat(2), 1n(1), 1ink(8) 
Linux, 24 July 1993 


sync 


sync— Commits buffer cache to disk 


SYNOPSIS 


#include <unistd.h> 
int sync(void); 


DESCRIPTION 


sync first commits inodes to buffers, and then buffers to disk. 


RETURN VALUE 


sync always returns @. 


CONFORMS TO 
SVID, AT&T, X/OPEN, BSD 4.3 


BUGS 


According to the standard specification (for example SVID ), sync() schedules the writes, but it might return before the 
actual writing is done. H oweve,, since version 1.3.20, Linux does actually wait. (T his still does not guarantee data integrity; 
modern disks have large caches.) 


SEE ALSO 
bdflush(2), fsync(2), fdatasync(2), update(8), sync(8) 
Linux 1.3.88, 15 April 1995 


sysctl 


sysct1— Reads/writes system parameters 


SYNOPSIS 


#include <unistd.h> 

#include <linux/unistd.h> 

#include <linux/sysctl.h> 

_syscalli(int_sysct! , struct _ sysctl_args *args); 
int sysctl(struct _ sysctl_args *args); 


DESCRIPTION 


The sysct1 call reads and/or writes kernel parameters— for example, the hostname or the maximum number of open files. 
The argument has the form 


struct __sysctl_args { 
int *name; /* integer vector describing variable */ 
int nlen; /* length of this vector */ 
void *oldval; /* @ or address where to store old value */ 
size_t *oldlenp; /* available room for old value, 


870 Part II: System Calls 


overwritten by actual size of old value */ 
void *newval; /* @ or address of new value */ 
size_t newlen; /* size of new value */ 
}; 


This call does a search in a tree structure, possibly resembling a directory tree under /proc/sys, and, if the requested item is 
found, calls some appropriate routine to read or modify the value 


EXAMPLE 


#include <linux/unistd.h> 
#include <linux/types.h> 
#include <linux/sysctl.h> 


_syscalli(int, _sysctl, struct _ sysctl args *, args); 
int sysctl(int *name, int nlen, void *oldval, size_t *oldlenp, 
void *newval, size_t newlen) 
{ 
struct __sysctl__args args={name,nlen,oldval,oldlenp,newval,newlen}; 
return _sysctl(&args) ; 
} 


#define SIZE(x) sizeof(x)/sizeof(x[®]) 
#define OSNAMESZ 100 


char osname [OSNAMESZ] ; 
int osnamelth; 
int name[] = { CTL_KERN, KERN_OSTYPE }; 


main(){ 
osnamelth = SIZE(osname) ; 
if (sysctl(name, SIZE(name), osname, &osnamelth, 0, )) 
perror("sysctl"); 
else 
printf("This machine is running %*s\n", osnamelth, osname) ; 
return Q; 
} 
RETURN VALUES 
Upon successful completion, sysct1 returnse. Otherwise a value of -1 is returned, and errno isse to indicate the eror. 
ERRORS 
ENOTDIR name Was not found. 
EPERM No search permission for one of the encountered directories, or no read permission where ol dval 
was nonzero, or no write permission wherenewval was nonzero. 
EFAULT Theinvocation asked for the previous value by setting ol dval non-N ULL, but allowed zero room 
in oldlenp. 
CONFORMS TO 
This call is Linux specific. 
HISTORY 


A sysct1 Call has bem present in Linux since version 1.3.57. It originated in BSD -4.4. Only Linux has the /proc/sys mirror, 
and the object-naming schenes differ between Linux and BSD 4.4, but the declaration of the sysct1(2) function is the same 
in both. 
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BUGS 
N ot all available objects are properly documented. 
It is not yet possible to change operating system by writing to /proc/sys/kernel/ostype. 


SEE ALSO 
proc(5) 
Linux 1.3.85, 11 April 1996 


sysfs 


systs— Gets filesystem type information 
SYNOPSIS 


int sysfs(int option, const char * fsname); 
int sysfs(int option, unsigned int fs_index, char * buf); 
int sysfs(int option); 


DESCRIPTION 


sysfs returns information about the filesystem types currently present in the kernel. The specific form of the sysfs call and 

the information returned depend on the option in effect. You can 

Translate the filesystem identifier stringfsname into a filesystem type index. 

M@ Translate thefilesysten type indexfs_index into anull-terminated filesystem identifier string. T his string will be written 
to the buffer pointed to by buf . M ake sure that buf has enough space to accept the string. 

m Return thetotal number of filesystem types currently present in the kernd. 


Thenumbering of the filesystem type indexes begins with 0. 
RETURN VALUE 


On success, sysfs returns the filesystem index for the first option, @ for the second option, and the number of currently 
configured filesystems for the third option. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 
EINVAL fsname isnot a valid filesystem type identifier; fs_index isout of bounds; option isinvalid. 
EFAULT Either fsname or buf isoutside your accessible address space. 

CONFORMS TO 
System V 


Linux 1.3.16, 9 August 1995 


sysinto 
sysinfo— Reurnsinformation on overall system statistics 
SYNOPSIS 


As of Linux 0.99.10 and image release 4.4, 


#include <linux/kernel.h> 
#include <linux/sys.h> 
int sysinfo(struct sysinfo *info); 
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DESCRIPTION 
sysinfo returns information in the following structure: 


struct sysinfo { 
long uptime; /* Seconds since boot */ 
unsigned long loads[3]; /* 1, 5, and 15 minute load averages */ 
unsigned long totalram; /* Total usable main memory size */ 
unsigned long freeram; /* Available memory size */ 
unsigned long sharedram; /* Amount of shared memory */ 
unsigned long bufferram; /* Memory used by buffers */ 
unsigned long totalswap; /* Total swap space size */ 
unsigned long freeswap; /* swap space still available */ 


unsigned short procs; /* Number of current processes */ 
char _f[22]; /* Pads structure to 64 bytes */ 
hs 
sysinfo provides a simple way of getting overall systen statistics. This is more portable than reading /dev/kmem. 
RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 
ERRORS 
EFAULT Thepointe to struct sysinfo iSinvalid. 
CONFORMS TO 
This function is Linux specific. 
BUGS 


The Linux DLL 4.4.1 libraries do not contain a proper prototype for this function. 
Linux 0.99.10, 24 July 1993 


syslog 


syslog— Reads and/or clears kernd message ring buffer; sets console_loglevel 


SYNOPSIS 


#include <unistd.h> 

#include <linux/unistd.h> 

_syscall3(int syslog, int type, char *bufp, int len); 
int syslog(int type, char *bufp, int len); 


DESCRIPTION 


This is probably not the function you are interested in. Look at sys1og(3) for the C library interface. T his page only 
documents the bare kernel system call interface. 


Thetype argument determines the action taken by syslog. 
From kernel/printk.c:/* 
Valid commands to syslog are 


o— Closethe log. Currently aN OP. 
i—Ope thelog. Currently aNOP. 
2— Read from the log. 


3— Read up to the last 4K B of messages in the ring buffer. 
4— Read and clear last 4KB of messages in the ring buffer. 
5— Clear ring buffer. 


6— Disable printks to console. 
7— Enable printksto console 


8— Se level of messages printed to console 


Only function 3 is allowed to non-root processes. 


THE KERNE 


The kernel has a cyclic buffer of length Log_Bur_Len (4096) in which messages given as argument to the kernel function 


LLOG BUFFER 


printk() are stored (regardless of ther loglevd). 


Theca 


buf. It returns then 


read on 


Thecal 
was wri 


Theca 
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syslog (4, 


<= 





THE LOGLEVEL 


The kernel routine printk() will print a message on the console only if it has a loglevel less than the value of the variable 
console_loglevel (initially DEFAULT CONSOLE_LOGLEVEL (7), but set to 10 if the kernel command line contains the word debug, 


,!en) does precisay the same, but also executes the “clear ring buffer” command. 
syslog (5,dummy ,i dummy ) Only executes the “clear ring buffer” command. 


syslog 


,!en) Waits until this kernel log buffer is nonempty, and then reads at most! en bytes into the buffer 
umber of bytes read. Bytes read from the log disappear from the log buffer; the information can only be 
ce Thisis the function executed by the kernd when auser program reads /proc/kmsg. 


syslog (3,buf ,len) Will read the last | en bytes from thelog buffer (nondestructively), but will not read more than 
tten into the buffer since the last “clear ring buffer” command (which does not clear the buffer at all). It returns the 
number of bytes read. 
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and to 15 in case of akernel fault— the 10 and 15 are just silly, and are equivalent to 8). T his variable is set (to a value in the 


range 1-8) by the call syslog (8,dummy ,value). T hecall syslog (type, dummy ,i dummy ) with type equal to 6 or 7, setsit to 1 
(kernel panics only) or 7 (all except debugging messages), respectively. 


Every text line in a message has its own loglevel. This level is DEFAULT_MESSAGE_LOGLEVEL-1 (6) unless the line starts with <d> 


where d isadigit in the range 1-7, in which case the level isd. The conventional meaning of the loglevel is defined in <1inux/ 


kernel. 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


RETURN V. 


n> as follows: 
KERN EMERG = "<>" 
KERN ALERT = "<1>" 
KERN_CRIT "<2>" 
KERN_ERR "<B>" 


KERN_WARNING "<4>" 
KERN_NOTICE '"<5>" 
KERN_INFO "<6>" 
KERN_DEBUG ‘<7o" 


ALUE 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


system is unusable 

action must be taken immediately 
critical conditions 

error conditions 

warning conditions 

normal but significant condition 
informational 

debug-level messages 


*/ 
"/ 
*/ 
*/ 
*/ 
eh 
| 
| 


In case of error, -1 iSreturned, and errno is set. On success, fort ype equal to 2, 3, or 4, syslog() returns thenumber of bytes 
read; otherwise, it returns o. 


ERRORS 


EPERM 


EINVAL 
ERESTAR 


An attempt was madeto change console_loglevel or clear the kernel message ring buffer by a 


process without root permissions. 
Bad parameters. 


TSYS System call was interrupted by a signal— nothing was read. 
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CONFORMS TO 


This system call is Linux specific. 


SEE ALSO 


syslog(3) 
Linux 1.2.9, 11 June1995 


termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcf lush, 
tcf low, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, 
tcgetpgrp, tcsetpgrp 


termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed 
tegetpgrp, tcsetpgrp— Get and set terminal attributes, do line control, get and set baud rate, get and set terminal foreground 
process group ID 


SYNOPSIS 


#include <termios.h> 

#include <unistd.h> 

int tegetattr ( int fd, struct termios *termios p ); 

int tcsetattr ( int fd, int optional actions, struct termios *termios_p ); 
int tcsendbreak ( int fd, int duration ); 

int tcdrain ( int fd ); 

int tcflush ( int fd, int queue selector ); 

int tcflow ( int fd, int action ); 

speed_t cfgetospeed ( struct termios *termios_p ); 

int cfsetospeed ( struct termios *termios_p, speed_t speed ); 
speed_t cfgetispeed ( struct termios *termios p ); 

int cfsetispeed ( struct termios *termios_p, speed_t speed ); 
pid_t tcgetpgrp ( int fd ); 

int tcsetpgrp ( int fd, pid_t pgrpid ); 


DESCRIPTION 


The termios functions describe a general terminal interface that is provided to control asynchronous communications ports. 


M any of the functions described here have ater mi os_p argument that isa pointer to atermios structure. T his structure 
contains the following members: 


tcflag_t c_iflag; /* input modes */ 
tcflag_t c_oflag; /* output modes */ 
tcflag_t c_cflag; /* control modes */ 
tcflag_t c_lflag;/*local modes*/ 

cc_t c_cc[NCCS]; /* control chars */ 


The following are the c_if!ag flag constants: 


IGNBRK Ignore BREAK Condition on input. 

BRKINT If 1anBRK iSnot set, generate SIGINT ON BREAK Condition; otherwise, read BREAK as character \0. 
IGNPAR Ignore framing errors and parity errors. 

PARMRK If 1GNPAR iSnot set, prefix a character with a parity error or framing error with \377 \0. If neither 


IGNPAR Nor PARMRK is Set, read a character with a parity error or framing error as \0. 
INPCK Enable input parity checking. 


termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfseti seed, 875 
cfsetogpead, tcgetpgrp, tcsetpgrp 


ISTRIP Strip off the eighth bit. 

INLCR Translate NL to CR on input. 

IGNCR Ignore carriage return on input. 

ICRNL Translate carriage return to newline on input (unless tencr is set). 

IUCLC M ap uppercase characters to lowercase on input. 

IXON Enable XON/XOFF flow control on output. 

IXANY Enable any character to restart output. 

IXOFF EnableXON/XOFF flow control on input tmaxeeL ring bell when input queue is full. 


The following are the c_oflag flag constants: 





OPOST Enable implementation-defined output processing. 

OLCUC M ap lowercase characters to uppercase on output. 

ONLCR Map NL to CR-NL on output. 

OCRNL Map CR to NL on output. 

ONOCR Don’t output CR at column 0. 

ONLRET Don’t output CR. 

OFILL Send fill characters for a delay rather than use a timed delay. 

OFDEL Fill character is ASCII DEL. If unset, fill character is ASCII NUL. 

NLDLY N ewline delay mask. Values are NLo and NL1. 

CRDLY Carriagereturn dday mask. Values are cro, cR1, CR2, and cR3. 

TABDLY H orizontal-tab delay mask. Values are TABO, TAB1, TAB2, TAB3, and xTABS. A value of xTABS expands 
tabs to spaces (with tab stops every aight columns). 

BSDLY Backspace dday mask. V alues are Bs@ and Bs1. 

VTDLY Vertical-tab dday mask. Values are vto and vT1. 

FFDLY Form-feed delay mask. V alues are FFo and FF1. 





The following are the c_cflag flag constants: 


CSIZE Character size mask. V alues are css, cs6, cs7,and css. 

CSTOPB Se two stop bits rather than one 

CREAD Enable receiver. 

PARENB Enable parity generation on output and parity checking for input. 

PARODD Parity for input and output is odd. 

HUPCL Lower modem control lines after last process closes the device (hangs up). 
CLOCAL Ignore modem control lines. 

CIBAUD M ask for input speeds (not used). 

CRTSCTS Flow control. 


The following are the c_1flag flag constants: 


ISIG W hen any of the characters InTR, QUIT, SUSP, OF DSUSP are received, generate the corresponding 
signal. 

ICANON Enables canonical mode. This allows the special characters EOF, EOL, EOL2, ERASE, KILL, REPRINT, 
STATUS, and WERASE, and also buffers by lines. 

XCASE If canon is also set, terminal is uppercase only. Input is converted to lowercase, except for 


characters preceded by \. On output, uppercase characters are preceded by \, and lowercase 
characters are converted to uppercase. 


ECHO Echo input characters. 
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ECHOE If IcANON iS also set, the erase character erases the preceding input character, and werase erases the 
preceding word. 

ECHOK If IcANON iS also set, the KILL character erases the current line 

ECHONL If IcANoN iS also set, echo the nt character even If EcHo is not set. 

ECHOCTL If EcHo is also set, ASCII control signals other than Tas, NL, START, and stop are echoed as Ctrl4+X, 
where X isthe character with ASCII code 0x10 greater than the control signal. For example, 
character 0x28 (BS) is echoed asCtrl+H . 

ECHOPRT If TCANON and IECHO are also set, characters are printed as they are being erased. 

ECHOKE If IcANON iS also set, KILL is echoed by erasing each character on the line, as specified by EcHoe and 
ECHOPRT. 

FLUSHO O utput is being flushed. T his flag is toggled by typing the prscarp character. 

NOFLSH Disables flushing of the input and output queues when generating the stant and sicaurT signals, 
and flushing of the input queue when generating the s1asusp signal. 

TOSTOP Sends the sreTTou signal to the process group of a background process that tries to write to its 
controlling terminal. 

PENDIN All characters in the input queue are reprinted when the next character is read. (bash handles 
typeahead this way.) 

IEXTEN Enable implenentation-defined input processing. 


tegetattr() gets the parameters associated with the object referred by fd and stores than in the termios structure referenced 
bytermios_p. This function may beinvoked from a background process; however, the terminal attributes may be subse- 
quently changed by a foreground process. 


tesetattr() sets the parameters associated with the terminal (unless support is required from the underlying hardware that is 
not available) from the termios structure referred to by termios_p.optional actions Specifies when the changes take effect: 


TCSANOW The change occurs immediately. 

TCSADRAIN The change occurs after all output written to fd has been transmitted. T his function should be used 
when changing parameters that affect output. 

TCSAFLUSH The change occurs after all output written to the object referred to by fd has been transmitted, and 


all input that has been received but not read will be discarded before the change is made. 


tcsendbreak() transmits a continuous stream of zero-valued bits for a specific duration, if the terminal is using asynchronous 
serial data transmission. If duration ise, it transmits zero-valued bits for at least 0.25 seconds, and not more than 0.5 
seconds. If duration iSnoto, it sends zero-valued bits for duration*N seconds, whereN isat least 0.25, and not more 

than 0.5. 


If the terminal is not using asynchronous sevial data transmission, tcsendbreak() returns without taking any action. 
tcdrain() waits until all output written to the object referred to by td has been transmitted. 


tcflush() discards data written to the object referred to bytd but not transmitted, or data received but not read, depending 
on the value of queue_selector: 


TCIFLUSH Flushes data received but not read. 
TCOFLUSH Flushes data written but not transmitted. 
TCIOFLUSH Flushes both data received but not read and data written but not transmitted. 


tcflow() suspends transmission or reception of data on the object referred to by#d, depending on the value of acti on: 


TCOOFF Suspends output. 
TCOON Restarts suspended output. 
TCIOFF Transmits a stop character, which stops the taminal device from transmitting data to the system. 


TCION Transmits a start character, which starts the terminal device transmitting data to the system. 


termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispead, cfseti seed, 
cfsetogpead, tcgetpgrp, tcsetpgrp 
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The default on open of a terminal file isthat nather its input nor its output is suspended. 


The baud rate functions are provided for getting and setting the values of the input and output baud rates in the termios 
structure. The new values do not take effect until tcsetattr() is successfully called. 


Setting the speed to Bo instructs the modem to hang up. The actual bit rate corresponding to 838400 may be altered with 
setserial(8). 


Theinput and output baud rates are stored in the termios structure. 
cfgetospeed() returns theoutput baud rate stored in the termios structure pointed to by termios_p. 


cfsetospeed() sets theoutput baud rate stored in the termios structure pointed to by termios_p to speed, which must beone 
of these constants: 
BO 

B50 

B75 
B110 
B134 
B150 
B200 
B300 
B600 
B1200 
B1800 
B2400 
B4800 
B9600 
B19200 
B38400 
B57600 
B115200 
B230400 


The zero baud rate, Be, is used to terminate the connection. If Bo is specified, the modem control lines will no longer be 
asserted. N ormally, this will disconnect the line. cBaupex is a mask for the speeds beyond those defined in PO SIX.1 (57600 
and later). T hus, 857600 & CBAUDEX isnonzeo. 


cfgetispeed() returns theinput baud rate stored in the termios structure. 


cfsetispeed() sets theinput baud rate stored in the termios structure to speed. If theinput baud rate is set to a, it will be 
equal to the output baud rate 


tcgetpgrp() returns the process group |D of the foreground processing group, or -1 on error. 
tesetpgrp() sets the process group ID to pgrpid. pgrpid must be the ID of a process group in the same session. 


RETURN VALUES 
cfgetispeed() returns theinput baud rate stored in the termios structure. 
cfgetospeed() returns theoutput baud rate stored in the termios structure 





tegetpgrp() returns the process group ID of foreground processing group, or -1 on error. 
All other functions return 
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@ On success. 
-1 on failure (and set errno to indicate the error). 


SEE ALSO 


setserial(8) 


time 
time— Gets timein seconds 


SYNOPSIS 


#include <time.h> 
time_t time(time_t *t); 


DESCRIPTION 
time returns the time since 00:00:00 GMT, January 1, 1970, measured in seconds. 
If t isnon null, the return value is also stored in the memory pointed to byt. 


CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


(Under BSD 4.3, this call is made obsolete by gett imeofday(2).) 
SEE ALSO 


ctime(3), date(1), ftime(3), gettimeofday(2) 


times 


times— Gets process times 


SYNOPSIS 


#include <sys/times.h> 
clock_t times(struct tms *buf); 


DESCRIPTION 
times stores the current process times in buf . 
struct tms iSas defined in /usr/include/sys/times.h: 


struct tms { 
time_t tms_utime; /* user time */ 
time_t tms_stime; /* system time */ 
time_t tms_cutime; /* user time of children */ 
time_t tms_cstime; /* system time of children */ 
hs 


times returns the number of clock ticks that have elapsed since the system has bem up. 


Linux, 25 February 1995 


Linux, 24 July 1993 
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CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 


time(1), getrusage(2), wait(2) 
Linux 0.99.11, 24 July 1993 


truncate, ftruncate 
truncate, ftruncate— T runcateafile to a specified length 


SYNOPSIS 


#include <unistd.h> 
int truncate(const char *path, size_t length); 
int ftruncate(int fd, size_t length); 


DESCRIPTION 


truncate Causes the filenamed by path or referenced by fd to be truncated to at most! ength bytesin size If thefile 
previously was larger than this size, the extra data is lost. W ith ftruncate, the file must be open for writing. 


RETURN VALUE 
On success, 0 isreturned. On error, -1 is returned, and errno is set appropriately. 
ERRORS 
The errors for truncate are 
ENOTDIR A component of the path prefix is not a directory. 
EINVAL The pathname contains a character with the high-order bit set. 
ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire pathname exceeded 1,023 
characters. 
ENOENT The named file does not exist. 
EACCES Search permission is denied for acomponent of the path prefix. 
EACCES The named file is not writeable by the user. 
ELOOP Too many symbolic links were encountered in translating the pathname 
EISDIR Thenamed file is a directory. 
EROFS Thenamed file resides on a read-only filesystem. 
ETXTBSY Thefile is a pure procedure (shared text) file that is being executed. 
EIO An 1|/O error occurred updating the inode 
EFAULT path points outside the process's allocated address space. 


Theerrors for ftruncate are 


EBADF fd isnot a valid descriptor. 

EINVAL fd references a socket, not afile 

EINVAL fd isnot open for writing. 
HISTORY 


T hese function calls appeared in BSD 4.2. 
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BUGS 


T hese calls should be generalized to allow ranges of bytes in a file to be discarded. 


SEE ALSO 
open(2) 
BSD Man Page 24 July 1993 


umask 


umask— Sets a file-creation mask 


SYNOPSIS 


#include <sys/stat.h> 
int umask(int mask); 


DESCRIPTION 


umask sets the umask to mask & 0777. 


RETURN VALUE 


The previous value of the mask is returned. 


CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 


creat(2), open(2) 
Linux 24 July 93 


uname 


uname— Gets name and information about the current kernd 


SYNOPSIS 


#include <sys/utsname.h> 
int uname(struct utsname *buf ); 


DESCRIPTION 
uname returns system information in buf. Theutsname struct is as defined in /usr/include/sys/utsname.h: 


struct utsname { 
char sysname[65]; 
char nodename[65]; 
char release[65]; 
char version[65]; 
char machine[65]; 
char domainname[65] ; 
}; 


RETURN VALUE 


On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


afs syscall, break, gtty, lock, mpx, prof, quotactl, sty, ustat 881 


ERRORS 

EFAULT buf iSnot valid. 
CONFORMS TO 

SVID, AT&T, POSIX, X/OPEN 
SEE ALSO 


uname(1), getdomainname(2), gethostname(2) 


Linux 0.99.11 24 July 93 


none 


none— Undocumented systen calls 


SYNOPSIS 


Undocumented system calls. 


DESCRIPTION 


As of Linux 1.3.88, there are 163 system calls listed in /usr/include/asm/unistd.h. T hisman page mentions those calls that 
are implemented in the kernd but not yet documented in man pages. Some of these calls do not yet have prototypes in the 
libc include files. 


SOLICITATION 


If you have information about these system calls, please look in the kernel source code, write aman page (using a style similar 
to that of the other Linux section 2 man pages), and send it to aeb@cwi.n1 for inclusion in the next man page rdease from the 
Linux Documentation Project. 


STATUS 


Undocumented are msync, readv, writev, getsid, fdatasync, sysctl, sched_setparam, sched_getparam, sched_setscheduler, 
sched_getscheduler, sched_yield, sched_get_priority_max, sched_get_priority_min, sched_rr_get_interval. 


SEE ALSO 


obsolete(2), unimplemented(2) 
Linux 1.3.86 12 April 1996 


afs syscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat 


afs_syscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat— Unimplemented system calls 


SYNOPSIS 


Unimplemented system calls. 


DESCRIPTION 


T hese system calls are not implemented in the Linux 1.2.4 kernd. 


RETURN VALUE 


T hese system calls always return -1 and set errno to ENosYS. 
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SEE ALSO 


obsolete(2), undocumented(2) 
Linux 1.2.4, 15 April 1995 


unlink 


unlink— D eletes anameand possibly the file it refers to 


SYNOPSIS 


#include <unistd.h> 
int unlink(const char *pathname); 


DESCRIPTION 


unlink deletes aname from the filesystem. If that name was the last link to afile and no processes have the file open, the file 
is deleted, and the space it was using is made available for reuse 


If the name was the last link to a file but any processes still have the file open, the file will remain in existence until the last 
file descriptor referring to it is closed. 


If the name referred to a symbolic link, the link is renoved. 


If the name referred to a socket, fifo, or device, the name for it is renoved but processes that have the object open can 
continue to use it. 


RETURN VALUE 
On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 
ERRORS 
EFAULT pathname points outside your accessible address space. 
EACCES W rite access to the directory containing pathname isnot allowed for the process's effective UID, or 
one of the directories in pathname did not allow search (execute) permission. 
EPERM The directory containing pathname has thesticky bit (s_tsvtx) set, and the process's effective UID is 
nathe theUID of thefile to be deleted nor that of thedirectory containing it, or pathname isa 
directory. 
ENAMETOOLONG pathname Was too long. 
ENOENT A directory component in pat hname doesnot exist or isa dangling symbolic link. 
ENOTDIR A component used asa directory in pat hname isnot, in fact, a directory. 
EISDIR pathname refers to adirectory. 
ENOMEM Insufficient kernel memory was available. 
EROFS pathname refers to afile on a read-only filesystem. 
CONFORMS TO 

SVID, AT&T, POSIX, X/OPEN, BSD 4.3 
BUGS 

Infdicities in the protocol underlying N FS can cause the unexpected disappearance of files that are still being used. 
SEE ALSO 


link(2), rename(2), open(2), rmdir(2), mknod(2), mkfifo(3), remove(3), rm(1), untink(8). 
Linux, 24 July 1993 
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uselib 


uselib— Sdects shared library 
SYNOPSIS 


#include <unistd.h> 
int uselib(const char *library); 


DESCRIPTION 
uselib selects the shared library binary that will be used by this process. 

RETURN VALUE 
On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 
In addition to all the error codes returned by open(2) and mmap(2), the following may also be returned: 
ENOEXEC Thefile specified by |i brary isnot executable, or does not have the correct magic numbers. 
EACCES Thelibrary specified by |i brary isnot readable. 

CONFORMS TO 
uselib() iS Linux specific. 

SEE ALSO 


open(2), mmap(2), 1dd(1), gec(1), ar(1), 10(1) 
Linux 0.99.11, 24 July 1993 


ustat 


ustat— Gets filesystem statistics 
SYNOPSIS 


#include <sys/types.h> 
int ustat(dev_t dev, struct ustat * ubuf); 


DESCRIPTION 
ustat returns information about a mounted filesystem. dev isa device number identifying a device containing a mounted 
filesystem. ubuf isapointer to austat structure that contains the following menbers: 


daddr_t f_tfree; /* Total free blocks */ 
ino_t f_tinode; /* Number of free inodes */ 
char f_fname[6]; /* Filsys name */ 

char f_fpack[6]; /* Filsys pack name */ 


The last two fields, f_fname and f_fpack, arenot implemented and will always be filled with null characters. 
RETURN VALUE 


On success, 0 is returned, and the ustat structure pointed to by ubuf will be filled in. On error, -1 isreturned, and errno is 
set appropriately. 
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ERRORS 

EINVAL dev does not refer to a device containing a mounted filesystem. 

EFAULT ubuf points outside of your accessible address space. 

ENOSYS The mounted filesystem referenced by dev does not support this operation, or any version of Linux 

before 1.3.16. 

NOTES 

ustat has been provided for compatibility only. All new programs should use statfs(2) instead. 
HISTORY 

ustat was first implanented in Linux 1.3.16. All versions of Linux before 1.3.16 will return Enosys. 
CONFORMS TO 

System V 
SEE ALSO 


statfs(2), stat(2) 
Linux 1.3.16, 9 August 1995 


utime, utimes 


utime, utimes— Change access and/or modification times of an inode 


SYNOPSIS 


#include <sys/types.h> 

#include <utime.h> 

int utime(const char *filename, struct utimbuf *buf ); 
#include <sys/time.h> 

int utimes(char *filename, struct timeval *tvp); 


DESCRIPTION 


utime changes the access and modification times of the inode specified by filename to theactime and modtime fields of buf, 
respectively. If buf isN ULL, the access and modification times of the file are set to the current time T heutimbuf structure is 
struct utimbuf { 

time_t actime; /* access time */ 

time_t modtime; /* modification time */ 

hs 

In the Linux D LL 4.4.1 libraries, utimes is just a wrapper for utime, tvp[@].tv_sec iSactime, aNdtvp[1].tv_sec ISmodtime. 
The timeval structure is 


struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 
}; 


RETURN VALUE 


On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 


vm86 885 


ERRORS 
O ther errors may occur. 
EACCESS Permission to write the file is denied. 
ENOENT filename does not exist. 
CONFORMS TO 


utime: SVID, POSIX 
utimes:BSD 4.3 


SEE ALSO 
stat(2) 
Linux, 10 June1995 


vhangup 
vhangup— Virtually hangs up the current tty 


SYNOPSIS 


#include <unistd.h> 
int vhangup(void) ; 


DESCRIPTION 


vhangup simulates a hangup on the current terminal. T his call arranges for other users to have a clean tty at login time 


RETURN VALUE 


On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 


ERRORS 


EPERM The user isnot the superuser. 


SEE ALSO 
init(8) 
Linux 0.99.11, 24 July 1993 


vm86 


vma6— Enters virtual 8086 mode 


SYNOPSIS 


#include <sys/vm86.h> 
int vm86(struct vm86_struct * info); 


DESCRIPTION 
Enter VM 86 mode with information as specified in i nfo: 


struct vm86_struct { 
struct vm86_regs regs; 
unsigned long flags; 
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unsigned long screen_bitmap; 


* normal regs, with special meaning for the segment descriptors.. 





ebx; 
@CX; 
edx; 
esi; 
edi; 
ebp; 
eax; 


__null_ds; 
__null_es; 
__null_fs; 
__null_gs; 


orig_eax; 
eip; 

cs; 
eflags; 
esp; 

$s; 


specific to v86 mode: 


es; 
ds; 
fs; 
gs; 


these are specific to v86 mode: 


On success, a isreturned. On error, -1 iSreturned, and errno is set appropriately. 


}; 
struct vm86_regs { 
T* 
bad 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ong 
ys 
* these are 
*/ 
ong 
ong 
ong 
ong 
}; 
/ 
long es; 
long ds; 
long fs; 
long gs; 
}; 
RETURN VALUE 
ERRORS 
EPERM 


Saved kernel stack exists. 
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wait, waitpid— W ait for process tamination 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/wait.h> 
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pid_t wait(int *status ) 
pid_t waitpid(pid_t pid,int*status ,int options); 


DESCRIPTION 


Thewait function suspends execution of the current process until a child has exited, or until a signal is delivered whose 
action is to terminate the current process or to call a signal-handling function. If a child has already exited by the time of the 
call (a so-called zombie process), the function returns immediately. Any system resources used by the child are freed. 


The waitpid function suspends execution of the current process until a child as specified by the pi d argument has exited, or 
until a signal is ddivered whose action is to taeminate the current process or to call a signal-handling function. J ust as with 
wait, if achild requested by pid has already exited by the time of the call, the function returns immediatdy. Any systen 
resources used by the child are freed. 


The value of pi d can be one of the following: 


<-1 W ait for any child process whose process group ID is equal to the absolute value of pid. 
-1 W ait for any child process; this is the same behavior that wait exhibits. 

Q W ait for any child process whose process group ID is equal to that of the calling process. 
> 0 W ait for the child whose process |D is equal to the value of pid. 


The value of options isan OR of zero or more of the following constants: 


WNOHANG Return immediately if no child has exited. 
WUNTRACED Also return for children that are stopped and whose status has not been reported. 


If status iSNOt NULL, wait Or waitpid stores status information in the location pointed to by stat! oc. 


This status can be evaluated with the following macros (these macros take the stat buffer as an argument— not a pointer to 
the buffer!): 


WIFEXITED(st atus ) Is nonzero if thechild exited normally. 


WEXITSTATUS (st at us ) Evaluates to the least significant eight bits of the return code of the child that terminated, which 
may have been set as the argument to a call to exit() or as the argument for a return statement 
in themain program. T his macro can only be evaluated if wiFexitep returned nonzero. 


WIFSIGNALED (status ) Returns true if the child process exited because of a signal that was not caught. 

WTERMSIG(status ) Returns the number of the signal that caused the child process to taminate. T his macro can 
only be evaluated if wrFSIGNALep returned nonzero. 

WIFSTOPPED (status ) Returns true if the child process that caused the return is currently stopped; this is only possible 
if the call was done using wuNTRACED. 

WSTOPSIG(status) Returns the number of the signal that caused the child to stop. T his macro can only be 


evaluated if wrFstoppep returned nonzero. 


RETURN VALUE 


Theprocess!ID of the child that exited returns -1 on error or o if WNOHANG was used and no child was available (in which case 
errno is set to an appropriate value). 


ERRORS 
ECHILD If the child process specified in pid does not exist. 
EPERM If the effective user 1D of the calling process does not match that of the process being waited 
for, and the effective user |D of the calling process is not that of the superuser. 
ERESTARTSYS If WNOHANG was not set and an unblocked signal or a s1GcHLp was caught; this is an extension to 


the PO SIX.1 standard. 
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CONFORMS TO 
POSIX.1 


SEE ALSO 
signal(2), wait4(2), signal(7) 
Linux, 24 July 1993 


wait3, wait4 


wait3, wait4a— W ait for process termination, BSD style 


SYNOPSIS 


#define _USE_BSD 

#include <sys/types.h> 

#include <sys/resource.h> 

#include <sys/wait.h> 

pid_t wait3(int *status,int options, 

struct rusage *rusage); 

pid_t wait4(pid_t pid,int*status ,int options, 
struct rusage *rusage); 


DESCRIPTION 


The waits function suspends execution of the current process until a child has exited, or until a signal is ddivered whose 
action is to taminate the current process or to call a signal-handling function. If a child has already exited by the time of the 
call (a zombie process), the function returns immediately. Any system resources used by the child are freed. 


The wait4 function suspends execution of the current process until a child as specified by the pid argument has exited, or 
until a signal is ddivered whose action is to taminate the current process or to call a signal-handling function. If achild as 
requested by pid has already exited by the time of the call (a zombie process), the function returns immediatdy. Any system 
resources used by the child are freed. 


The value of pi d can be one of the following: 


<-1 W ait for any child process whose process group ID is equal to the absolute value of pid. 
-1 W ait for any child process; this is equivalent to calling waits. 

) W ait for any child process whose process group ID is equal to that of the calling process. 
> 0 W ait for the child whose process |D is equal to the value of pid. 


The value of options isan exclusive OR of zero or more of the following constants: 


WNOHANG Return immediately if no child is there to be waited for. 
WUNTRACED Also return for children that are stopped and whose status has not been reported. 


If status iSnOt NULL, wait3 and wait4 store status information in the location pointed to bystatioc. 


This status can be evaluated with the following macros: 


WIFEXITED(*status ) Is nonzero if thechild exited normally. 

WEXITSTATUS(*st atus ) Evaluates to the least significant eight bits of the return code of the child that terminated, which 
may have bean set as the argument to a call to exit or as the argument for areturn statement in 
the main program. This macro can only be evaluated if wrFexrtep returned nonzero. 

WIFSIGNALED(*status ) Returns true if the child process exited because of a signal that was not caught. 

WTERMSIG(*st atus ) Returns the number of the signal that caused the child process to taminate. T his macro can 
only be evaluated if wrFSIGNALep returned nonzero. 
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WIFSTOPPED(*status ) Returns true if the child process that caused the return is currently stopped; this is only possible 
if the call was done using wuNTRACED. 
WSTOPSIG(*status ) Returns the number of the signal that caused the child to stop. T his macro can only be 


evaluated if wiFstoprep returned nonzero. If rusage isnot NULL, the struct rusage as defined in 
<sys/resource.h> it points to will be filled with accounting information. See getrusage(2) for 
details. 


RETURN VALUE 


T hese calls return the process!D of the child that exited, -1 on error, or @ if wNoHANG was used and no child was available (in 
which case errno will be set appropriately). 


ERRORS 
ECHILD If the child process specified in pid does not exist. 
EPERM If the effective user 1D of the calling process does not match that of the process being waited 
for, and the effective user |D of the calling process is not that of the superuser. 
ERESTARTSYS If WNOHANG was not set and an unblocked signal or a s1@cHLD was caught; this is an extension to 
the PO SIX.1 standard. 
CONFORMS TO 
POSIX.1 
SEE ALSO 


signal(2), getrusage(2), wait(2), signal(7) 
Linux, 24 July 1993 


write 


write— W rites to a file descriptor 


SYNOPSIS 


#include <unistd.h> 
ssize_t write(int fd, const void *buf, size_t count); 


DESCRIPTION 
write writes up to count bytes to the file referenced by the file descriptor fd from the buffer starting at but . POSIX requires 
that a read() that can be proved to occur after awrite() returned returns thenew data. N ote that not all filesystens are 
POSIX conforming. 


RETURN VALUE 


On success, the number of bytes written is returned (0 indicates nothing was written). On error, -1 isreturned, and errno is 
set appropriately. If count is@ and the file descriptor refers to a regular file, @ will be returned without causing any other 
effect. For aspecial file, the results are not portable. 


ERRORS 
EBADF fd isnot a valid file descriptor or is not open for writing. 
EINVAL fd is attached to an object that is unsuitable for writing. 


EFAULT buf isoutside your accessible address space. 
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EPIPE fd is connected to a pipe or socket whose reading end is closed. W hen this happens, the writing 
process will receive a stGP1Pe signal; if it catches, blocks, or ignores this, the error EPrPE is 
returned. 

EAGAIN N on-blocking !/O has been selected using o_NonBLock, and there was no room in the pipe or 
socket connected to fd to write the data immediately. 

EINTR The call was interrupted by a signal before any data was written. 

ENOSPC The device containing the file referred to by fd hasno room for the data. 


O ther errors may occur, depending on the object connected to fd. 


CONFORMS TO 
SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


SEE ALSO 
open(2), read(2), fent1(2), close(2), 1seek(2), select(2), ioct1(2), fsync(2), fwrite(3) 
Linux, 13 January 1996 






Library Functions 


Part III: Library Functions 





Intro 
DESCRIPTION 
This chapter describes all the library functions, excluding the library functions described in Part 2, which implement system 
calls. The various function groups are identified by aletter that is appended to the chapte: number: 
(3C) T hese functions— the functions from Chapter 2 and from Chapter 3S— are contained in theC standard 
library libc, which will be used by cc(1) by default. 
(3S) T hese functions are parts of the stdio(3S) library. They are contained in the standard C library 1ibc. 
(3M ) T hese functions are contained in the arithmetic library 1ibm. T hey are used by the #77(1) FORTRAN 
compiler by default, but not by thecc(1) C compiler, which needs the option -! m. 
(3F) T hese functions are part of the FORTRAN library 1ibF77. T here are no special compiler flags needed to 
use these functions. 
(3X) Various special libraries. The manual pages documenting thar functions specify the library names. 
AUTHORS 
Look at the header of the manual page for the author(s) and copyright conditions. N ote that these can be different from page 
to page! 


Linux, 13 D ecanber 1995 


abort 


abort— C auses abnormal program termination 


SYNOPSIS 


#include <stdlib.h> 
void abort(void); 


DESCRIPTION 


The abort() function causes abnormal program termination unless the signal staaBorT is caught and the signal handler does 
not return. If the abort() function causes program termination, all open streams are closed and flushed. 


If the steaBort function is blocked or ignored, the abort() function will still override it. 


RETURN VALUE 


The abort() function never returns. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3,1SO 9899 


SEE ALSO 
sigaction(2), exit(3) 
GNU, 12 April 1993 


abs 


abs— Computes the absolute value of an integer 


SYNOPSIS 


#include <stdlib.h> 
int abs(int | ); 


DESCRIPTION 


The abs() function computes the absolute value of the integer argument j . 


RETURN VALUE 


Returns the absolute value of the integer argument. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


NOTES 
Trying to take the absolute value of the most negative integer is not defined. 


SEE ALSO 


ceil(3), floor(3), fabs(3), labs(3), rint(3) 
GNU, 6 June1993 


acos 


acos— Arc cosine function 


SYNOPSIS 


#include <math.h> 
double acos(double x); 


DESCRIPTION 


The acos() function calculates the arc cosine of x; that is the value whose cosineis x. If x falls outside the range -1 to 1, 
acos() failsand errno is set. 


RETURN VALUE 
The acos() function returns the arc cosine in radians; the value is mathenatically defined to be between 0 and pi (inclusive). 
ERRORS 
EDOM x iS out of range 
CONFORMS TO 
SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 


asin(3), atan(3), atan2(3), cos(3), sin(3), tan(3) 
8 June1993 


acosh 


acosh— Inverse hyperbolic cosine function 
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SYNOPSIS 


#include <math.h> 
double acosh(double x); 


DESCRIPTION 


The acosh() function calculates the inverse hyperbolic cosine of x; that is the value whose hyperbolic cosineisx. If x is less 
than 1.0, acosh() returns not-a-number (N aN ), and errno is set. 


ERRORS 


EDOM x iS out of range. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
asinh(3), atanh(3), cosh(3), sinh(3), tanh(3) 
13 June1993 


alloca 


alloca— M emory allocator 


SYNOPSIS 


#include <stdlib.h> 
void *alloca( size_t size); 


DESCRIPTION 


The alloca function allocates size bytes of space in the stack frame of the caller. Thistemporary space is automatically freed 
on return. 


RETURN VALUES 


The alloca function returns a pointer to the beginning of the allocated space. If the allocation fails, a NULL pointer is 
returned. 


CONFORMS TO 


There is evidence that the alloca function appeared in 32v, pwb, pwb.2, 3bsd, and 4bsd. There is aman page for it in BSD 
4.3. Linux uses the GNU version. 


BUGS 


The alloca function is machine dependent. 


SEE ALSO 
prk(2), pagesize(2), calloc(3), malloc(3), realloc(3) 
GNU, 29 Novenber 1993 


asin 


asin— Arc sine function 


SYNOPSIS 


#include <math.h> 
double asin(double x); 


DESCRIPTION 


Theasin() function calculates the arc sine of x, which is the value whose sine isx. If x falls outside the range -1 to 1, asin() 
fails and errno is set. 


RETURN VALUE 


Theasin() function returns the arc sine in radians, and the value is mathematically defined to be between -Pr/2 and p1/2 
(inclusive). 


ERRORS 


EDOM x iS out of range. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
acos(3), atan(3), atan2(3), cos(3), sin(3), tan(3) 
8 June1993 


asinh 


asinh— Inverse hyperbolic sine function 


SYNOPSIS 


#include <math.h> 
double asinh(double x); 


DESCRIPTION 


The asinh() function calculates the inverse hyperbolic sine of x— that is, the value whose hyperbolic sineisx. 


CONFORMS T0 
SVID 3, POSIX, BSD 4.3,1SO 9899 


SEE ALSO 
acosh(3), atanh(3), cosh(3), sinh(3), tanh(3) 
13 June1993 


assert 


assert— Abort the program if assertion is false 


SYNOPSIS 


#include <assert.h> 
void assert (int expression); 
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DESCRIPTION 


assert() prints an error message to standard output and terminates the program by calling abort() if expression is false (that 
is, evaluates to @). This only happens when the macro npeBus is undefined. 


RETURN VALUE 


No valueis returned. 


CONFORMS T0 
1SO 9899 (ANSI C) 


BUGS 


assert() isimplemented as a macro; if the expression tested has side effects, program behavior will be different depending on 
whether noesue is defined. T his may create H eisenbugs, which go away when debugging is turned on. 


SEE ALSO 
exit(3), abort(3) 
GNU, 4 April 1993 


atan 


atan— Arc tangent function 


SYNOPSIS 


#include <math.h> 
double atan(double x); 


DESCRIPTION 
The atan() function calculates the arc tangent of x — that is, the value whose tangent is x. 
RETURN VALUE 
The atan() function returns the arc tangent in radians, and the value is mathematically defined to be between -P1/2 and p1/2 
(inclusive). 
CONFORMS TO 
SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 
acos(3), asin(3), atan2(3), cos(3), sin(3), tan(3) 
8 June1993 
atan2 
atan2— Arc tangent function of two variables 
SYNOPSIS 


#include <math.h> 
double atan2(double y, double x); 
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DESCRIPTION 


The atan2() function calculates the arc tangent of the two variables, x andy. It is similar to calculating the arc tangent of y/x, 
except that the sines of both arguments are used to determine the quadrant of the result. 


RETURN VALUE 


The atan2() function returns the result in radians, which is between -pr and pz (inclusive). 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
acos(3), asin(3), atan(3), cos(3), sin(3), tan(3) 
8 June1993 


atanh 


atanh— Inverse hyperbolic tangent function 


SYNOPSIS 


#include <math.h> 
double atanh(double x); 


DESCRIPTION 


The atanh() function calculates the inverse hyperbolic tangent of x; that is the value whose hyperbolic tangent isx. If the 
absolute value of x is greater than 1.0, acosh() returns not-a-number (N aN ), and errno is set. 


ERRORS 

EDOM x iS out of range. 
CONFORMS TO 

SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 

asinh(3), acosh(3), cosh(3), sinh(3), tanh(3) 

13 June1993 

atexit 

atexit— Register a function to be called at normal program termination 
SYNOPSIS 


#include <stdlib.h> 
int atexit(void *function)(void)); 


DESCRIPTION 
The atexit() function registers the given function to be called at normal program termination, whether via exit(2) or via 
return from the program’s main. Functions so registered are called in the reverse order of their registration; no arguments are 
passed. 
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RETURN VALUE 


The atexit() function returns the value o if successful; otherwise, the value -1 is returned, and the global variable errno is set 
to indicate the error. 


ERRORS 

ENOMEM Insufficient memory available to add the function. 
CONFORMS TO 

SVID 3, BSD 4.3, 1SO 9899 
SEE ALSO 


exit(3), on exit(3) 
GNU, 29 March 1993 


atof 


atof— Convaet a string to adouble 


SYNOPSIS 


#include <stdlib.h> 
double atof(const char *nptr); 


DESCRIPTION 
The atotf() function converts the initial portion of the string pointed to by nptr to double The behavior is the same as 
strtod(nptr, (char **)NULL); 


except that atof() does not detect errors. 


RETURN VALUE 


The converted value. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3,1SO 9899 


SEE ALSO 
atoi(3), atol(3), strtod(3), strto1(3), strtoul(3) 
GNU, 29 March 1993 


atol 


atoi— Convat a string to an integer 


SYNOPSIS 


#include <stdlib.h> 
int atoi(const char *nptr); 
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DESCRIPTION 
The atoi() function converts the initial portion of the string pointed to by nptr to int. The behavior is the same as 
strtol(nptr, (char **)NULL, 10); 


except that atoi() does not detect errors. 


RETURN VALUE 
The converted value. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
atof(3), ato1(3), strtod(3), strto1(3), strtoul(3) 
GNU, 29 March 1993 


atol 


atol— Convat a string to along integer 


SYNOPSIS 


#include <stdlib.h> 
long atol(const char *nptr); 


DESCRIPTION 
The ato1() function converts the initial portion of the string pointed to by nptr to long. The behavior isthe same as 
strtol(nptr, (char **)NULL, 10); 


except that ato1() does not detect errors. 


RETURN VALUE 
The converted value. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
atof(3), atoi(3), strtod(3), strto1(3), strtoul(3) 
GNU, 29 March 1993 


bemp 


bemp— C ompare byte strings 
SYNOPSIS 


#include <string.h> 
int bemp(const void *sl, const void *s2, int n); 
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DESCRIPTION 


The bemp() function compares the first n bytes of the stringss1 and s2. If the two strings are equal, bemp() returns a; 
otherwise it returns anonzero result. If n iso, thetwo strings are assumed to be equal. 


RETURN VALUE 

The bemp() function returns @ if the strings are equal; otherwise, a nonzero result is returned. 
CONFORMS TO 

4.3BSD . This function is deprecated— use mememp in new programs. 
SEE ALSO 


memcmp(3), strcasecmp(3), stremp(3), strco11(3), strncmp(3), strncasecmp(3) 
GNU, 9 April 1993 


bcopy 


bcopy— Copy byte strings 
SYNOPSIS 


#include <string.h> 
void bcopy (const void *src, void*dest, int n); 


DESCRIPTION 


The beopy() function copies the first n bytes of the source stringsrc to the destination string dest. Ifn iSO, no bytes are 
copied. 


RETURN VALUE 


The beopy() function returns no value. 


CONFORMS TO 


4.3BSD . This function is deprecated— use memcpy in new programs. 


SEE ALSO 


memccpy(3), memcpy(3), memmove(3), strcepy(3), strncpy(3) 
GNU, 9 April 1993 


bsearch 


bsearch— Binary search of a sorted array. 


SYNOPSIS 


#include <stdlib.h> 
void *bsearch(const void *key, const void *base, size_t nmemb, 
size_t size,int(*compar )(const void *, const void *)); 


The bsearch() function searches an array of nmemb objects, the initial manber of which is pointed to by base, for amember 
that matches the object pointed to by key. The size of each member of the array is specified by size. 


The contents of the array should bein ascending sorted order according to the comparison function referenced by compar. 


htonl, htons, ntohl, ntohs 


Thecompar routine is expected to have two arguments that point to thekey object and to an array member, in that order, and 
should return an integer less than, equal to, or greater than 0, respectively, if thekey object is found to be less than, match, or 
be greater than the array member. 


RETURN VALUE 


The bsearch() function returns a pointer to a matching member of thearray, or NuLL if no match is found. If there are 
multiple elements that match the key, the dement returned is unspecified. 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 


qsort(3) 
GNU, 29 March 1993 


bemp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memf rob, 
memmem, memmove, memset 


bemp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, memmove, memset— Byte string operations 


SYNOPSIS 


#include <string.h> 

int bemp(const void *sl, const void *s2, int n); 
void bcopy(const void *src, void *dest, int n); 
void bzero(void *s, int n); 
void *memccpy(void *dest, const void *src, int c, size t n); 
void *memchr(const void *s, int c, size_t n); 
int memcmp(const void *sl1, const void *s2, size_t n); 
void *memcpy(void *dest, const void *src, size_t n); 
void *memfrob(void *s, size_t n); 
void *memmem(const void *needle, size t needlelen, 
const void *haystack, size_t haystacklen); 

void *memmove(void *dest, const void *src, size_t n); 
void *memset(void *s, int c, size_t n); 


DESCRIPTION 


The byte string functions perform operations on strings that are not NULL terminated. See the individual man pages for 
descriptions of each function. 


SEE ALSO 


bemp(3), bcopy(3), bzero(3), memecpy(3), memchr(3), memcmp(3), memcpy(3), memfrob(3), memmem(3), memmove(3), memset(3) 
GNU, 12 April 1993 





htonl, htons, ntohl, ntohs 


htonl, htons, ntohl, ntohs— C onvert values between host and network byte order 


SYNOPSIS 


#include <netinet/in.h> 
unsigned long int htonl(unsigned long int hostlong); 
unsigned short int htons(unsigned short int hostshort); 
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unsigned long int ntohl(unsigned long int netlong); 
unsigned short int ntohs(unsigned short int netshort); 


DESCRIPTION 
The hton1() function converts the long integer host! ong from host byte order to network byte order. 
The htons() function converts the short integer host short from host byte order to network byte order. 
The nton1() function converts the long integer net! ong from network byte order to host byte order. 
The ntohs() function converts the short integer net short from network byte order to host byte order. 


On the i80x86, the host byte order is least significant byte first, whereas the network byte order, as used on the Internet, is 
most significant byte first. 


CONFORMS T0 
BSD 4.3 


SEE ALSO 


gethostbyname(3), getservent(3) 
BSD, 15 April 1993 


bzero 


bzero— W rites os to a byte string 


SYNOPSIS 


#include <string.h> 
void bzero(void *s, int n); 


DESCRIPTION 
The bzero() function setsthe first n bytes of the byte strings to 0. 


RETURN VALUE 


The bzero() function returns no value. 


CONFORMS TO 


4.3BSD . This function is deprecated— use memset in new programs. 
SEE ALSO 
memset(3), swab(3) 
GNU, 9 April 1993 


catgets 


catgets— Gets message from a message catalog 


SYNOPSIS 


#include <features.h> 

#include <nl_types.h> 

char *catgets(nl_catd catalog, int set_number, int 
message_number, char *message) ; 


catopen, catclose 
DESCRIPTION 


catgets() reads the message message_number, in Se set_number, from the message catalog identified by catalog. (catalog isa 
catalog descriptor returned from an earlier call to catopen(3).) The fourth argument message points to a default message 
string that will be returned by catgets() if the identified message catalog is not currently open or is damaged. T he message 
text is contained in an internal buffer area and should be copied by the application if it is to be saved or modified. The return 
string is always terminated with anull byte. 


RETURN VALUES 


On SUCCESS, catgets() returns apointe to an internal buffer area containing the null-terminated message string. catgets() 
returns a pointer to message if it fails because the message catalog specified by catalog is not currently open. O therwise, 
catgets() returns a pointer to an empty string if the message catalog is available but does not contain the specified message. 


NOTES 


T hese functions are only available in 1ibc.so.4.4.4c and above. 


SEE ALSO 


catopen(3), setlocale(3) 
29 N ovember 1993 


catopen, catclose 


catopen, catclose— O pen/close a message catalog 


SYNOPSIS 


#include <features.h> 

#include <nl_types.h> 

nl catd catopen(char *name, int flag); 
void catclose(nl_catd catalog); 


DESCRIPTION 


catopen() Opens a message catalog and returns a catalog descriptor. name specifies the name of the message catalog to be 
opened. If name specifies an absolute path (that is, contains a/), name specifies a pathname for the message catalog. O therwise, 
the environment variable NLSPATH is used, with name substituted for %n (See locale(5)). If NLSPATH does not exist in the 
environment, or if amessage catalog cannot be opened in any of the paths specified by n-spatu, the following paths are 
searched in order: 

/etc/locale/LC_MESSAGES 


/usr/lib/locale/LC_MESSAGES 
/usr/lib/locale/name/LC_MESSAGES 


In all cases, Lc_messaces stands for the current setting of the Lc_messaces category of locale from a previous call to 
setlocale() and defaults to the C” locale. In the last search path, name refers to the catalog name. 


Thefl ag argument to catopen is used to indicate the type of loading desired. This should be either wcLoaaBySet Or MCLoadA11. 
The former value indicates that only the required set from the catalog is loaded into menory when needed, whereas the latter 
causes the initial call to catopen() to load the entire catalog into memory. 


catclose() closes the message catalog identified by cat a! og. It invalidates any subsequent references to the message catalog 
defined by catalog. 


RETURN VALUES 


catopen() returns a message catalog descriptor of typen1_catd on success. On failure, it returns -1. 
catclose() returns 0 on SUCCESS, or -1 on failure. 
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NOTES 


T hese functions are only available in libc.so.4.4.4c and above. In the case of Linux, the catalog descriptor n1_cata is actually 


an area of memory assigned by mmap() and not a file descriptor, thus allowing catalogs to be shared. 


SEE ALSO 


catgets(3), setlocale(3) 


ceil 
ceil— Smallest integral value not less than x 


SYNOPSIS 


#include <math.h> 
double ceil (double x); 


DESCRIPTION 


Theceil() function rounds up x to the nearest integer, returning that value as a double. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3, 1SO 9899 


SEE ALSO 
abs(3), fabs(3), floor(3), 1abs(3), rint(3) 


clientlib 


clientlib— NNTP clientlib part of InterN €&tN ews library 
SYNOPSIS 


extern FILE *ser_rd_fp; 

extern FILE *ser_wr_fp; 

extern char ser_line[]; 

char * getserverbyfile(file); 

char *file; int server_init(host ); 
char *host; 

int handle_server_response(response, host); 
int reponse; 

char *host ; 

void put_server(text); 

char *text; 

int get_server(buff, buffsize); 
char *buff; 

int buffsize; 

void close_server(); 


DESCRIPTION 


30 N ovenber 1993 


6 June1993 


The routines described in this manual page are part of the InterN etN ews library, 1ibinn(3). They are reolacenents for the 


clientlib part of the NNTP distribution, and are intended to be used in building programs such asrrn. 


closedir 


getserverbyfile Calls GetConfigValue to get thenameof the local NNTP server. It returns a pointer to static space. Thetile 
parameter is ignored. 


server_init opens a connect to the NNTP server at the specified host . It returns the server's response code or -1 on error. If 
a connection was made, ser_rd_fp and ser_wr_fp can be used to read from and write to the server, respectively, and ser_line 
will contain the server's response ser_line can also be used in other routines. 


handle_server_response decodes the response, which comes from the server on host . 1f the client is authorized, it returns 0. A 
client that is only allowed to read is authorized, but handle_server_response will print a message on the standard output. If 
the client is not authorized to talk to the server, a message is printed, and the routine returns -1. 


put_server sends the text in buff to theserver, adding the necessary N NTP lineterminators and flushing thel/O buffer. 


get_server readsa line of text from the server into buff, reading at most buffsize characters. Any trailing \r\n terminators 
are stripped off. get_server returns -1 on error. 


close_server sends a quit command to the server and closes the connection. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


libinn(3) 


clock 


clock— D etermine processor time 


SYNOPSIS 


#include <time.h> 
clock_t clock (void); 


DESCRIPTION 


The clock() function returns an approximation of processor timeused by the program. 


RETURN VALUE 


The value returned is the CPU time used so far a5 aclock_t; to get the number of seconds used, divide by cLocks_PER_SEC. 


CONFORMS TO 


ANSI C 


BUGS 


TheC standard allows for arbitrary values at the start of the program; take the difference betwem the value returned from a 
Call to clock() at the start of the program and the value returned at the end for maximum portability. 


The times() function call returns more information. 


SEE ALSO 


times(2) 
GNU, 21 April 1993 


closedir 


closedir— Closea directory 


Part III: Library Functions 


SYNOPSIS 


#include <sys/types.h> 
#include <dirent.h> 
int closedir(DIR *dir); 


DESCRIPTION 
The closedir() function closes the directory stream associated with dir. The directory stream descriptor dir isnot available 
after this call. 
RETURN VALUE 
The closedir() function returns on success or -1 on failure 
ERRORS 
EBADF Invalid directory stream descriptor dir. 
CONFORMS TO 
SVID 3, POSIX, BSD 4.3 
SEE ALSO 
close(2), opendir(3), readdir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 
11 June1995 
confstr 
confstr— Ge configuration-dependent string variables 
SYNOPSIS 
#define __USE_POSIX_2 
#include <unistd.h> 
size_t confstr(int name, char *buf , size t len); 
DESCRIPTION 
confstr() gets the value of configuration-dependent string variables. 
Thename argument is the system variable to be queried. T he following variables are supported: 
CS_PATH A value for the PATH variable that indicates where all the PO SIX.2 standard utilities can be found. 


If buf isnot NULL, andi en isnot 0, confstr() copies the value of the string to buf truncated to len-1 characters if necessary, 
with a null character as termination. This can be detected by comparing the return value of confstr() against | en. 


If len iS@ and buf iSNULL, confstr() just returns the value in Return Value. 


RETURN VALUE 


If name does not correspond to a valid configuration variable confstr() returns a. 


EXAMPLES 
The following code fragment determines the path where you can find the PO SIX.2 system utilities: 


char *pathbuf; size_t n; 

n = confstr(_CS_PATH,NULL, (size_t)Q); 

if ((pathbuf = malloc(n)) == NULL) abort(); 
confstr(_CS_PATH, pathbuf, n); 


cos 907 


ERRORS 
If the value of name iSinvalid, errno is set to EINVAL. 
CONFORMS TO 
Proposed PO SIX.2 
BUGS 
POSIX.2 isnot ye an approved standard; the information in this man page is subject to change. 
SEE ALSO 


sh(1), exec(2), system(3) 
GNU, 17 April 1993 


copysign 
copysign— C opiesthesign of anumber 


SYNOPSIS 


#include <math.h> 
double copysign(double x, double y); 


DESCRIPTION 


The copysign() function returns a value whose absolute value matches x, but whose sign matches that of y. 


CONFORMS TO 
BSD 4.3 
GNU, 6 June1993 


COS 


cos— Cosine function 


SYNOPSIS 


#include <math.h> 
double cos(double x); 


DESCRIPTION 


Thecos() function returns the cosine of x, where x isgiven in radians. 


RETURN VALUE 


Thecos() function returns a value between -1 and 1. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
acos(3), asin(3), atan(3), atan2(3), sin(3), tan(3) 
8 June1993 
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cosh 


cosh— H yperbolic cosine function 


SYNOPSIS 


#include <math.h> 
double cosh(double x); 


DESCRIPTION 


The cosh() function returns the hyperbolic cosine of x, which is defined mathematically as (exp(x)+exp(-x)) /2. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
acosh(3), asinh(3), atanh(3), sinn(3), tann(3) 
13 June1993 


crypt 


crypt— Password and data encryption 


SYNOPSIS 


#include <unistd.h> 
char *crypt(const char *key, const char *salt); 


DESCRIPTION 


crypt isthe password-encryption function. It is based on the D ata Encryption Standard algorithm, with variations intended 
(among other things) to discourage the use of hardware implementations of a key search. 


key iSauser’s typed password. 


salt iSatwo-character string chosen from the set [a-zA-z0-9./]. This string is used to perturb the algorithm in one of 4,096 
different ways. 


By taking the lowest seven bits of each character of the key, a 56-bit key is obtained. T his 56-bit key is used to repeatedly 
encrypt a constant string (usually a string consisting of all os). The returned value points to the encrypted password, a series 
of 13 printable ASCII characters (with the first two characters representing the salt itself). The return value points to static 
data whose content is overwritten by each call. 


Warning: T he key space consists of equal 7.2e16 possible values. Exhaustive searches of this key space are possible using 
massively parallel computers. Software, such as crack(1), is available to search the portion of this key space that is generally 
used by humans for passwords. H ence, password sdection should, at minimum, avoid common words and names. Using a 
passwd(1) program that checks for crackable passwords during the selection process is recommended. 

TheDES algorithm itsdf has a few quirks that make using the crypt(3) interface a very poor choice for anything other than 
password authentication. If you are planning to use the crypt(3) interface for a cryptography project, don’t do it; get a good 
book on encryption and one of the widdy available D ES libraries instead. 


CONFORMS TO 
SVID, X/OPEN, BSD 4.3 


asctime ctime gmtime localtime mktime 


SEE ALSO 


login(1), passwa(1), encrypt(3), getpass(3), passwa(5) 
3 Seotember 1994 


ctermid 


ctermid— Gets controlling terminal name 


SYNOPSIS 


#include <stdio.h> 
char *ctermid(char *s); 


DESCRIPTION 


ctermid() returns a string that isthe pathname for the current controlling terminal for this process. If s isNULL, a static buffer 
is used; otherwise, s points to a buffer used to hold the terminal pathname The symbolic constant L_ctermid isthe 
maximum number of characters in the returned pathname. 


RETURN VALUE 


This function returns the pointer to the pathname. 


CONFORMS TO 
POSIX.1 


BUGS 
The path returned might not uniqudy identify the controlling taeminal; it might, for example, be /dev/tty. 
It isnot assured that the program can open theteminal. 


SEE ALSO 


ttyname(3) 
GNU, 6 April 1993 


asctime, ctime, gmtime, Localtime, mktime 


asctime, ctime, gmtime, localtime, mktime— Transform binary date and time to ASCII 


SYNOPSIS 


#include <time.h> 

char *asctime(const struct tm *timeptr); 
char *ctime(const time_t *timep); 

struct tm *gmtime(const time_t *timep); 
struct tm *localtime(const time_t *timep); 
time_t mktime(struct tm *timeptr); 

extern char *tzname[2]; 

long int timezone; 

extern int daylight ; 


DESCRIPTION 
Thectime(), gmtime(), ANd localtime() functions all take an argument of data type time_t, which represents calendar time. 
W hen interpreted as an absolute time value, it represents the number of seconds dapsed since 00:00:00 on January 1, 1970, 
Coordinated Universal Time (UTC). 
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The asctime() and mktime() functions both take an argument representing broken-down time, which isa binary reoresenta- 
tion separated into year, month, day, and so on. Broken-down time is stored in the structuret m, which is defined in <time.h> 
as follows: 


struct tm 
{ 
int tm_sec; /* seconds */ 

int tm_min; /* minutes */ 

int tm_hour; /* hours */ 

int tm_mday; /* day of the month */ 

int tm_mon; /* month */ 

int tm_year; /* year */ 

int tm_wday; /* day of the week */ 

int tm_yday; /* day in the year */ 

int tm_isdst; /* daylight saving time */ 
}; 





Themembers of thet m structure are 


tm_sec The number of seconds after the minute, normally in the range 0 to 59, but can be up to 61 to allow for 
leap seconds. 

tm_min Thenumber of minutes after the hour, in the range 0 to 59. 

tm_hour The number of hours past midnight, in the range 0 to 23. 

tm_mday The day of the month, in the range 1 to 31. 

tm_mon The number of months since] anuary, in the range 0 to 11. 

tm_year The number of years since 1900. 

tm_wday The number of days since Sunday, in the range 0 to 6. 

tm_yday Thenumber of days since] anuary 1, in the range 0 to 365. 

tm_isdst A flag that indicates whether daylight savings timeis in effect at the time described. T he value is positive if 


daylight saving time isin effect, o if it isnot, and negative if the information isnot available 


The ctime()function converts the calendar timetimep into a string of the form 
"Wed Jun 30 21:49:08 1993\n" 


The abbreviations for the days of the week are sun, Mon , Tue, Wed, Thu, Fri, and sat. The abbreviations for the months are 
Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. T he return value points to a statically allocated string that might 
be overwritten by subsequent calls to any of the date and time functions. The function also sets the external variable tzname 
with information about the current timezone 


The gmtime() function converts the calendar time timeo to broken-down time representation, expressed in Coordinated 
Universal Time (UTC). 


The localtime() function converts the calendar timeti mep to broken-time representation, expressed relative to the user’s 
specified time zone. The function sets the external variablest zname with information about the current time zone, ti mezone 
with the difference between C oordinated Universal Time and local standard time in seconds, and day! i ght to anonzero 
value if standard U.S. daylight saving time rules apply. 


The asctime() function converts the broken-down time value ti meptr into a string with the same format as ctime(). The 
return value points to a statically allocated string that might be overwritten by subsequent calls to any of the date and time 
functions. 


The mktime() function converts a broken-down time structure, expressed as local time, to calendar time representation. T he 
function ignores the specified contents of the structure manbers tm_wday and tm_yday and recomputes them from the other 
information in the broken-down time structure Calling mktime() also sets the external variablet zname with information 
about the current time zone. If the specified broken-down time cannot be represented as calendar time mktime() returns a 
value of (time_t)(-1) and doesnot alter thet m wiay and tm yday members of the broken-down time structure. 


div 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


date(1), gettimeofday(2), time(2), tzset(3), difftime(3), strftime(3), newctime(3) 
BSD, 26 April 1996 


difftime 


diftftime— Calculates time difference 


SYNOPSIS 


#include <time.h> 
double difftime(time_t timel, time _t time0); 


DESCRIPTION 


The difftime() function returns the number of seconds elapsed between timeti me1 and timeti med. The two times are 
specified in calendar time, which represents the time dapsed since 00:00:00 on J anuary 1, 1970, Coordinated U niversal 
Time(UTC). 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 


date(1), gettimeofday(2), time(2), ctime(3), gmtime(3), localtime(3) 
GNU, 2 July1993 


div 
div— Computes the quotient and remainder of integer division 


SYNOPSIS 


#include <stdlib.h> 
div_t div(int numer, int denom); 


DESCRIPTION 


The div) function computes the value numer / denom and returns the quotient and remainder in a structure named aiv_t that 
contains two integer members named quot and rem. 


RETURN VALUE 


Thediv_t structure. 


CONFORMS T0 
SVID 3, BSD 4,3, 1SO 9899 


SEE ALSO 
ldiv(3) 
6 June1993 
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drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, 
seed48, lcong48 


drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48— G @erate uniformly distributed pseudo- 
random numbers 


SYNOPSIS 


#include <stdlib.h> 

double drand48(void) ; 

double erand48(unsigned short int xsubi [3]); 

long int lrand48(void) ; 

long int nrand48(unsigned short int xsubi [3]); 

long int mrand48(void) ; 

long int jrand48(unsigned short int xsubi [3]); 

void srand48(long int seedval ); 

unsigned short int * seed48(unsigned short int seedl6v [3]); 
void lcong48(unsigned short int param[7]); 


DESCRIPTION 
T hese functions generate pseudo-random numbers using the linear congruential algorithm and 48-bit integer arithmetic. 


The drand48() and erand48() functions return non-negative double-precision floating-point values uniformly distributed 
between [0.0, 1.0]. 


The 1rand48() and nrand4s() functions return non-negative long integers uniformly distributed between 0 and 2°31. 
The mrand48() and jrand48() functions return signed long integers uniformly distributed between -2731 and 2731. 


The srand48(),seed48(), and 1cong48() functions are initialization functions, one of which should be called before using 
drand48(), lrand48(), OF mrand49(). The functions erand48(), nrand48(), and jrand48() do not require an initialization 
function to be called first. 


All the functions work by generating a sequence of 48-bit integers, Xi, according to the linear congruential formula 
Xi+l={aXi+c) mod m, wherei >=0 
Theparameter m=2*48; hence 48-bit integer arithmetic is performed. U nless 1cong48() is called, a and care given by 


Q@x5DEECE66D 
QxB 


a 
c 


The value returned by any of the functions drand48(), erand48(), lrand48(), nrand48(), mrand48(), OF jrand48() is computed 
by first generating the next 48-bit xi in the sequence. Then the appropriate number of bits, according to the type of data 
itan to be returned, is copied from the high-order bits of xi and transformed into the returned value 


The functions drand4g(), 1rand48(), and mrand4g() store the last 48-bit xi generated in an internal buffer. T he functions 
erand48(), nrand48(), and jrand48() require the calling program to provide storage for the successivexi valuesin the array 
argument xsubi . The functions are initialized by placing the initial value of xi into the array before calling the function for 
the first time 


The initializer function srand4g() sets the high-order 32 bits of xi to the argument seedval . The low-order 16 bits are set to 
the arbitrary value 0x330E. 


The initializer function seea48() sets the value of xi to the 48-bit value specified in the array argument seed1l6v. The 
previous value of Xi is copied into an internal buffer and a pointer to this buffer is returned by seea48(). 


The initialization function 1cong48() allows the user to specify initial values for xi , a and c. Array argument elements 
param[0-2] specify xi , param[3-5] specify a, and param[6] specifies c. After 1cong48() has been called, a subsequent call to 
either srand48() OF seed48() will restorethe standard values of a and. 


ect, fevt fs | 


CONFORMS TO 
SVID 3 


NOTES 
T hese functions are declared obsolete by SVID 3, which states that rand(3) should be used instead. 


SEE ALSO 
rand(3), random(3) 
2 July 1993 


drem 


drem— Floating-point remainder function 


SYNOPSIS 


#include <math.h> 
double drem(double x, double y); 


DESCRIPTION 


Thedrem() function computes the remainder of dividingx byy. The return value is x-n*y, where n is the quotient of x 
divided by y, rounded to the nearest integer. If the quotient is ¥, it is rounded to the even number. 


RETURN VALUE 


The drem() function returns the renainder unless y is 0, in which case the function fails and errno is set. 


ERRORS 


EDOM The denominator y iso. 


CONFORMS T0 
BSD 4.3 


SEE ALSO 


fmod(3) 
6 June1993 


ecvt, fcvt 


ecvt, fevt— Convert a floating-point number to a string 


SYNOPSIS 


#include <stdlib.h> 
char *ecvt(double number , size_t ndigits,int*decpt ,int*sign); 
char *fcvt(double number , size_t ndigits,int*decpt ,int*sign); 


DESCRIPTION 


The ecvt() function converts number to a NULL-terminated string of ndi gits digits and returns a pointer to thestring. The 
string itsdf does not contain a decimal point; however, the position of the decimal point relative to the start of the string is 
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stored in decpt. A negative value for decpt means that the decimal point is to the left of the start of the string. If the sign of 
number iS negative, sign is set to anonzero value; otherwise, it’s set to 0. 


The fevt() function is identical to ecvt(), except that ndi gits specifies the number of digits after the decimal point. 


RETURN VALUE 


Both the ecvt()and fevt() functionsreturn a pointer to a static string containing the ASCII representation of number . The 
static string is overwritten by each call to ecvt() or fevt(). 


SEE ALSO 


gevt(3), sprintt(3) 
28 M arch 1993 


erf, erfc 


erf, erfc— Error function and complenentary error function 


SYNOPSIS 


#include <math.h> 
double erf(double x); 
double erfc (double x); 


DESCRIPTION 
Theerf() function returns the error function of x, defined as 
erf(x) = 2/sqrt(pi)* integral from @ to x of exp(-t*t) dt 


Theerfc() function returns the complementary error function of x— that is, 1.0-erf(x). 


CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 
exp(3) 
BSD, 25 June1993 


execl, execlp, execle, exect, execv, execvp 


execl, execlp, execle, exect, execv, execvp— Execute a file 


SYNOPSIS 


#include <unistd.h> 
extern char **environ; 





int execl(const char *path, const char *arg, ...); 

int execlp(const char *file, const char *arg, ...)3 

int execle(const char *path, const char *arg, ...)3 

int execlp(const char *file, const char *arg, ...)3 

int execle(const char *path, const char *arg, ...)3 

int execle(const char *path, const char *arg , ..., char * const envp[]); 
int exect(const char *path, char *const argv[]); 

int execv(const char *path, char *const argv[]); 

int execvp(const char *file, char *const argv[]); 


execl, execip, execle, exect, execy, execvp 
DESCRIPTION 


The exec family of functions replaces the current process image with a new process image. T he functions described in this 
manual page are front ends for the function execve(2). (See the manual page for execve for detailed information about the 
replacement of the current process.) 


The initial argument for these functions is the pathname of afile that is to be executed. 


The const char *arg and subsequent dlipses in the execl, execlp, and execle functions can be thought of aS arg@, arg1,..., 
argn. T ogether they describe a list of one or more pointers to null-terminated strings that represent the argument list 
available to the executed program. The first argument, by convention, should point to the file name associated with the file 
being executed. The list of arguments must be terminated by anuLt pointer. 


The exect, execv, and execvp functions provide an array of pointers to null-terminated strings that represent the argument 
list available to the new program. T hefirst argument, by convention, should point to the filename associated with the file 
being executed. T he array of pointers must be terminated by anuLt pointer. 





The execle and exect functions also specify the environment of the executed process by following thenuLt pointer that 
terminates the list of arguments in the parameter list or the pointer to theargv array with an additional parameter. This 
additional parameter is an array of pointers to null-terminated strings and must be terminated by anuLt pointer. The other 
functions take the environment for the new process image from the external variable environ in thecurrent process. 


Some of these functions have special semantics. 


The functions execip and execvp will duplicate the actions of the shell in searching for an executable file if the specified 
filename does not contain a slash (/) character. T he search path isthe path specified in the environment by the pat variable 
If this variable isn’t specified, the default path /bin:/usr/bin: is used (is this true for Linux?). In addition, certain errors are 
treated specially. 


If permission is denied for a file (the attempted execve returned eEacces), these functions will continue searching the rest of 
the search path. If no other file is found, however, they will return with the global variable errno set to EACCES. 


If the header of a file isn’t recognized (the attempted execve returned ENO EXEC), these functions will execute the shal with 
the path of the file as its first argument. (If this attempt fails, no further searching is done) 


If the file is currently busy (the attempted execve returned eTxtBusy), these functions will sleep for several seconds, periodi- 
cally reattempting to execute the file. (Is this true for Linux?) 


The function exect executes a file with the program-tracing facilities enabled (see ptrace(2)). 


RETURN VALUES 


If any of the exec functions returns, an error will have occurred. The return value is -1, and the global variable errno will be 
set to indicate the error. 


FILES 


/bin/sh 


ERRORS 


execl, execle, execlp, and execvp May fall and sé errno for any of the errors specified for the library functions execve(2) and 
malloc(3). 


exect and execv may fail and se@t errno for any of the errors specified for the library function execve(2). 


SEE ALSO 


sh(1), execve(2), fork(2), trace(2), environ(5), ptrace(2) 


COMPATIBILITY 


Historically, the default path for the execlp and execvp functions was /bin: /usr/bin. T his was changed to place the current 
directory last to enhance system security. 
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The behavior of execlp and execvp when errors occur while attempting to execute the file is historic practice, but has not 
traditionally been documented and is not specified by the PO SIX standard. 


Traditionally, the functions execlp and execvp ignored all errors except for the ones described above and ENomem and E2BIG, 
upon which they returned. T hey now return if any error other than the ones described in the “Errors” section occurs. 


STANDARDS 
execl, execv, execle, execlp, and execvp conform to IEEE Std1003.1-88 (PO SIX.1). 
BSD Man Page, 29 November 1993 


errno 


errno— N umber of last error 


SYNOPSIS 


#include <errno.h> 
extern int errno; 


DESCRIPTION 


Theinteger errno is set by system calls (and some library functions) to indicate what went wrong. Its value is significant only 
when the call returns an error (usually -1), and alibrary function that does succeed is allowed to change errno. 


Sometimes, when -1 is also a legal return value, you have to set errno to @ before the call in order to detect possible errors. 
POSIX lists the following symbolic error names: 


E2BIG Arg list too long 

EACCES Permission denied 

EAGAIN Resource temporarily unavailable 
EBADF Bad file descriptor 

EBUSY Resource busy 

ECHILD No child processes 
EDEADLK Resource deadlock avoided 
EDOM Domain error 

EEXIST File exists 

EFAULT Bad address 

EFBIG File too large 

EINTR Interrupted function call 
EINVAL Invalid argument 

EIO Input/output error 

EISDIR Isa directory 

EMFILE Too many open files 
EMLINK Too many links 
ENAMETOOLONG Filename too long 

ENFILE Too many open files in system 
ENODEV No such device 

ENOENT No such file or directory 
ENOEXEC Exec format error 

ENOLCK No locks available 


ENOMEM N ot enough space 
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ENOSPC No spaceleft on device 
ENOSYS Function not implemented 
ENOTDIR N ot adirectory 
ENOTEMPTY Directory not enpty 
ENOTTY Inappropriate !/O control operation 
ENXIO No such device or address 
EPERM O peration not permitted 
EPIPE Broken pipe 
ERANGE Result too large 
EROFS Read-only filesystem 
ESPIPE Invalid seek 
ESRCH No such process 
EXDEV Improper link 

SEE ALSO 
perror(3) 


21 July 1996 


exit 
exit— Causes normal program termination 


SYNOPSIS 


#include <stdlib.h> 
void exit(int status); 


DESCRIPTION 
The exit() function causes normal program termination, and the value of st atus is returned to the parent. All functions 
registered with atexit() and on exit() are called in the reverse order of thar registration, and all open streams are flushed 
and closed. 


RETURN VALUE 

Theexit() function does not return. 
CONFORMS TO 

SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 


_exit(2), atexit(3), on_exit(3) 
GNU, 2 April 1993 


exp, log, 10g10, pow 
exp, log, 10910, pow— Exponential, logarithmic, and power functions 


SYNOPSIS 


#include <math.h> 
double exp(double x); 
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double log(double x); 
double logi@(double x); 
double pow(double x, double y); 


DESCRIPTION 
The exp() function returns the value of e (the base of natural logarithms) raised to the power of x. 
The 10g) function returns the natural logarithm of x. 
The 10g10() function returns the base-10 logarithm of x. 
The pow) function returns the value of x raised to the power of y. 


ERRORS 
The 1og() and 10g10() functions can return the following errors: 
EDOM The argument x isnegative. 
ERANGE The argument x ise. Thelog of 0 is not defined. 


The pow) function can return the following error: 


EDOM Theargument x is negative and y is not an integral value This would result in a complex numbe’. 
CONFORMS TO 

SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 


sqrt(3), cbrt(3) 
GNU June16, 1993 


expmi, logip 
expm1, logip— Exponential minus 1, logarithm of 1 plus argument 


SYNOPSIS 


#include <math.h> 
double expm1 (double x); 
double logip (double x); 


DESCRIPTION 


expm1 (x) returns a value equivalent to exp (x)- 1. It is computed in a way that is accurate even if the value of x isnear 0O—a 
case where exp (x)-1 would be inaccurate due to subtraction of two numbers that are nearly equal. 


logip(x ) returnsa value equivalent to log (1 +x). It is computed in a way that is accurate even if the value of x is near 0. 


CONFORMS TO 
BSD 


SEE ALSO 
exp(3), 10g(3) 
GNU, 16 Septenber 1995 


clearerr, feof, ferror, fileno 
fabs 


Fabs— Absolute value of floating-point number 


SYNOPSIS 


#include <math.h> 
double fabs(double x); 


DESCRIPTION 


The fabs() function returns the absolute value of the floating-point number x. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
abs(3), ceil(3), floor(3), labs(3), rint(3) 
25 June1993 


fclose 


fclose— Closes a stream 


SYNOPSIS 


#include <stdio.h> 
int fclose(FILE *stream); 


DESCRIPTION 


The fclose function dissociates the named stream from its underlying file or set of functions. If the stream was being used for 
output, any buffered data is written first, using fflush(3). 


RETURN VALUES 


Upon successful completion, @ is returned. O therwise, Eor isreturned, and the global variable errno is set to indicate the 
error. In either case, no further access to the stream is possible 


ERRORS 
EBADF The argument stream is not an open stream. 
The fclose function may also fail and set errno for any of the errors specified for the routines close(2) or fflush(3). 


SEE ALSO 


close(2), fflush(3), fopen(3), setbuf(3) 


STANDARDS 
The fclose function conforms to AN SI C3.159-1989 (“ANSI C”). 


BSD Man Page, 29 November 1993 


clearerr, feof, ferror, fileno 


clearerr, feof, ferror, fileno— Check and reset stream status 


Part III: Library Functions 


SYNOPSIS 


#include <stdio.h> 

void clearerr( FILE *stream); 
int feof(FILE *stream); 

int ferror(FILE *stream); 
int fileno(FILE *stream); 


DESCRIPTION 
The function clearerr Clears the end-of-file and error indicators for the stream pointed to by stream. 


The function feot tests the end-of-file indicator for the stream pointed to bystream, returning nonzero if it isset. The end- 
of-file indicator can only be cleared by the function clearerr. 


The function ferror tests the error indicator for the stream pointed to by stream, returning nonzero if it is set. The error 
indicator can only be reset by the clearerr function. 


The function fileno examines the argument stream and returns its integer descriptor. 


ERRORS 


T hese functions should not fail and do not set the external variable errno. 


SEE ALSO 


open(2), stdio(3) 


STANDARDS 
The functions clearerr, feof, and ferror conform to C3.159-1989 (“ANSI C”), 
BSD Man Page, 29 November 1993 


fflush, fpurge 


fflush, fpurge— Flush a stream 


SYNOPSIS 


#include <stdio.h> 
int fflush( FILE *stream); 
int fpurge( FILE *stream); 


DESCRIPTION 


The function flush forces a write of all buffered data for the given output or update stream via the stream’s underlying write 
function. The open status of the stream is unaffected. 


If the stream argument iS NULL, fflush flushes all open output streams. (D oes this hagpen under Linux?) 


The function fpurge erases any input or output buffered in the given stream. For output streams, this discards any unwritten 
output. For input streams, this discards any input read from the underlying object but not yet obtained via getc(3); this 
includes any text pushed back via ungetc. 


RETURN VALUES 
Upon successful completion, @ is returned. O therwise, Eor isreturned, and the global variable errno is set to indicate the 
error. 

ERRORS 
EBADF Stream is not an open stream, or, in the case of fflush, not a stream open for writing. 


The function ff1ush may also fail and set errno for any of the errors specified for the routine write(2). 


fgetgrent 


BUGS 


Linux may not support fpurge. 


SEE ALSO 


write(2), fopen(3), fclose(3), setbut(3) 
STANDARDS 
The fflush function conforms to AN SI C3.159-1989 (“ANSI C”). 
BSD Man Page, 29 November 1993 


ffs 


ffs— Finds first bit set in a word 
SYNOPSIS 


#include <string.h> 
int ffs(int i); 


DESCRIPTION 
The ffs() function returns the postion of the first bit set in the word i. The least significant bit is position 1, and the most 
significant position 32. 

RETURN VALUE 


The ffs() function returns the position of the first bit set, or NULL if no bits are set. 


CONFORMS TO 
BSD 4.3 


GNU, 13 April 1993 


fgetgrent 


fgetgrent— Gets group file entry 


SYNOPSIS 


#include <grp.h> 

#include <stdio.h> 

#include <sys/types.h> 

struct group *fgetgrent(FILE *stream); 


DESCRIPTION 


The fgetgrent() function returns a pointer to a structure containing the group information from thefilestream. T he first 
time it is called it returns the first entry; thereafter, it returns successive entries. The filest ream must have the same format as 
/etc/group 


The group structure is defined in <grp.h> as follows: 


struct group { 


char *gr_name; /* group name */ 
char *gr_passwd; /* group password */ 
gid_t gr_gid; /* group id */ 


char **gr_mem; /* group members */ 
}; 


Part III: Library Functions 


RETURN VALUE 


The fgetgrent() function returns the group information structure, or nuLL if there are no more entries or an error occurs. 


ERRORS 


ENOMEM Insufficient memory to allocate group information structure. 


CONFORMS TO 
SVID 3 


SEE ALSO 


getgrnam(3), getgrgid(3), getgrent(3), setgrent(3), endgrent(3) 
GNU, 4 April 1993 


fgetpwent 


fgetpwent— Gets password file entry 


SYNOPSIS 


#include <pwd.h> 

#include <stdio.h> 

#include <sys/types.h> 

struct passwd *fgetpwent(FILE *stream); 


DESCRIPTION 


The fgetpwent() function returns a pointer to a structure containing the broken-out fidds of alinein thefilestream. The 
first timeit is called it returns the first entry; thereafter, it returns successive entries. The filest ream must have the same 
format as /etc/passwd. 


The passwd structure is defined in <pwd.h> as follows: 


struct passwd { 


char *pw_name; /* username */ 
char *pw_passwd; /* user password */ 
uid_t pw_uid; /* user id */ 
gid_t pw gid; /* group id */ 
char *pw_gecos; /* real name */ 
char *pw_dir; /* home directory */ 
char *pw_shell; /* shell program */ 
}; 
RETURN VALUE 
The fgetpwent() function returns the passwd structure, or NULL if there areno more entries or an error occurs. 
ERRORS 
ENOMEM Insufficient memory to allocate passwd structure 
FILES 
/etc/passwd password database file 
CONFORMS TO 


SVID 3 


fod fe 


GNU, 17 May 1996 


SEE ALSO 


getpwnam(3), getpwuid(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwent( 3), passwa(5) 


floor 


floor— Largest integral value not greater than x 


SYNOPSIS 


#include <math.h> 
double floor(double x); 


DESCRIPTION 


The floor() function rounds x downward to the nearest integer, returning that value as a double. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
abs(3), fabs(3), cei1(3), rint(3) 
6 June1993 


fmod 


fmod— Floating-point remainder function 


SYNOPSIS 


#include <math.h> 
double fmod(double x, double y); 


DESCRIPTION 


The modt() function computes the remainder of dividingx byy. The return value is x-n*y, where n is the quotient of x/y, 
rounded toward 0 to an integer. 


RETURN VALUE 
The fmoa() function returns the renainder unless y is 0, in which case the function fails and errno is set. 
ERRORS 
EDOM Thedenominator y is 0. 
CONFORMS TO 
SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 
drem(3) 


6 June1993 


Part III: Library Functions 


fnmatch 


fnmatch— M atches filename or pathname 


SYNOPSIS 


#include <fnmatch.h> 
int fnmatch(const char *pattern, const char *strings,int flags); 





DESCRIPTION 
fnmatch() checks thestrings argument and checks whether it matches the pattern argument, which isa shal wildcard 
pattern. 
Thefl ags argument modifies the behavior; it is the bitwise or of zero or more of the following flags: 
FNM_NOESCAPE If this flag is set, treat backslash as an ordinary character instead of as an escape character. 
FNM_PATHNAME If this flag is set, match aslash in string only with aslash in pattern and not, for example, with 

a[] - sequence containing a slash. 

FNM_PERIOD If this flag is set, a leading period in string has to be matched exactly by aperiod in pattern. A 


period is considered to be leading if it isthe first character in string, or if both FNM_PATHNAME iS 
set and the period immediately follows a slash. 


RETURN VALUE 
Zero if string matches pattern, FNM_NOMATCH if thereis no match, or another value if there is an error. 


CONFORMS TO 
Proposed PO SIX.2 


BUGS 


POSIX.2 isnot yet an approved standard; the information in this man page is subject to change 


SEE ALSO 
sh(1), glob(3), glob(7) 
GNU, 19 April 1993 


fopen, fdopen, freopen 


fopen, fdopen, freopen— Stream open functions 


SYNOPSIS 


#include <stdio.h> 

FILE *fopen( char *path, char *mode); 

FILE *fdopen( int fildes, char *mode); 

FILE *freopen( char *path, char *mode,FILE*stream); 


DESCRIPTION 
The fopen function opens the file whose name is the string pointed to by path and associates a stream with it. 


Theargument mode points to a string beginning with one of the following sequences (additional characters may follow these 
sequences): 


r Open text file for reading. The stream is positioned at the beginning of the file. 
r+ Open for reading and writing. The stream is positioned at the beginning of the file 


fpathconf, pathconf 


w Truncate file to zero length or create a text file for writing. The stream is positioned at the 
beginning of the file 

w+ Open for reading and writing. The file is created if it does not exist; otherwise it is truncated. 
The stream is positioned at the beginning of the file. 

a Open for writing. The file is created if it does not exist. The stream is positioned at the end of 
the file. 

at Open for reading and writing. The file is created if it does not exist. The stream is positioned at 


the end of the file. 


The mode string can also include the letter b either as a third character or asa character between the characters in any of the 
two-character strings described previously. Thisis strictly for compatibility with AN SI C 3.159-1989 (AN SI C) and has no 
effect; the b isignored. 


Any created files will have modes _IRUSR!S IWUSR'S IRGRP!S IWGRP'S IROTH!S IWOTH (0666), as modified by the process 
umask Value. (See umask(2).) 


Reads and writes may be intermixed on read/write streams in any order. N ote that AN SI C requires that a file positioning 
function intervene between output and input, unless an input operation encounters end-of-file (If this condition isnot met, 
then a read is allowed to return the result of writes other than the most recent.) T herefore it is good practice (and indeed 
sometimes necessary under Linux) to put an fseek Or fgetpos operation between write and read operations on such a stream. 
This operation may be an apparent no-op (asin fseek(..., @L, SEEK_CUR)) Called for its synchronizing side effect. 


The fdopen function associates a stream with the existing file descriptor, fildes. The mode of the stream must be compatible 
with the mode of the file descriptor. T he file descriptor is not duplicated. 


The freopen function opens the file whose nameis the string pointed to by path and associates the stream pointed to by 
stream with it. The original stream (if it exists) isclosed. The mode argument is used just as in the fopen function. The 
primary use of the freopen function is to change the file associated with a standard text stream (stderr, stdin, OF stdout). 


RETURN VALUES 


On successful completion, fopen, fdopen, and freopen return a FILE pointer. Otherwise, NULL is returned, and the global 
variable errno is set to indicate the error. 


ERRORS 
EINVAL The mode provided to fopen, fdopen, Or freopen was invalid. 
The fopen, fdopen, and freopen functions may also fail and set errno for any of the errors specified for the routine malloc(3). 
The fopen function may also fail and set errno for any of the errors specified for the routine open(2). 
The fdopen function may also fail and set errno for any of the errors specified for the routine fent1(2). 


The freopen function may also fail and set errno for any of the errors specified for the routines open(2), fclose(3) and 
fflush(3). 


SEE ALSO 


open(2), fclose(3) 


STANDARDS 


The fopen and freopen functions conform to AN SI C3.159-1989 (AN SI C). The fdopen function conforms to IEEE 
Std1003.1-1988 (PO SIX.1). 


BSD Man Page, 13 December 1995 


fpathconf, pathconf 


fpathconf, pathconf— Get configuration values for files 


Part III: Library Functions 


SYNOPSIS 


#include <unistd.h> 


long fpathconf(int filedes ,intname); 
long pathconf(char *path, int name); 


DESCRIPTION 


fpathconf() gets a value for the configuration option name for the open file descriptor filedes. 


pathconf() gets a value for configuration option name for the filename path. 


The corresponding macros defined in <unistd.h> are the minimum values; if an application wants to take advantage of values 
that may change, acall to fpathconf() OF pathconf() can be made, which may yield more liberal results. 


Setting name equal to one of the following constants returns the following configuration options: 


_PC_LINK_MAX 
_PC_MAX_CANON 
_PC_MAX_INPUT 
_PC_NAME_MAX 
_PC PATH_MAX 
_PC_PIPE_BUF 


_PC_CHOWN_RESTRICTED 


_PC_NO_TRUNC 


_PC_VDISABLE 


RETURN VALUE 


Returns the maximum number of links to the file If filedes or path refers to adirectory, the 
value applies to the whole directory. T he corresponding macro iS_POSIX_LINK_MAX. 
Returns the maximum length of a formatted input line wherefiledes or path must refer toa 
terminal. The corresponding macro iS _POSIX_MAX_CANON. 

Returns the maximum length of an input line wheretiledes or path must refer to a terminal. 
The corresponding macro is _PoSIX_MAX_INPUT. 

Returns the maximum length of a filenamein the directory path or filedes the process is 
allowed to create. The corresponding macro iS_POSIX_MAX_. 

Returns the maximum length of a relative pathname when path orfiledes isthe current 
working directory. The corresponding macro is_POSIX_PATH_MAX. 

Returns the size of the pipe buffer, wheretiledes must refer to apipeor FIFO, and path must 
refer to aFIFO. The corresponding macro is _PoSIX_PIPE_BUF. 

Returns nonzero if the chown(2) call may not beused on thisfile If filedes Orpath referstoa 
directory, this applies to all files in that directory. The corresponding macro is 
_POSIX_CHOWN_RESTRICTED. 

Returns nonzero if accessing filenames longer than _Pos1x_NAME_MAX generates an error. The 
corresponding macro iS_POSIX_NO_TRUNC. 

Returns nonzero if special character processing can be disabled, where fil edes Or path Must 
refer to a terminal. 








Thelimit is returned, if one exists. If the system does not havea limit for the requested resource, -1 is returned, and errno is 
unchanged. If there is an error, -1 iSreturned, and errno isse to reflect the nature of the error. 


CONFORMS TO 


POSIX.1. Files with name lengths longer than the value returned for name equal to _Pc_NAME_MAX may exist in the given 


directory. 


Somereturned values may be huge; they are not suitable for allocating memory. 


SEE ALSO 


getcont(1), statfs(2), open(2), syscont(3) 


fread, fwrite 


GNU, 4 April 1993 


fread, fwrite— Binary stream input/output 


fgetpos, fseck, fsetpos, ftell, rewind 927 


SYNOPSIS 


#include <stdio.h> 
size_t fread(void *ptr, size_t size, size_t nmemb ,FILE*stream); 
size_t fwrite(void *ptr, size t size, size_t nmemb ,FILE*stream); 


DESCRIPTION 


The function fread reads nmemb elements of data, each size bytes long, from the stream pointed to by stream, storing them at 
the location given by ptr. 


The function fwrite writes nmemb elements of data, each size bytes long, to the stream pointed to by stream, obtaining then 
from the location given by ptr. 


RETURN VALUES 


fread and fwrite return thenumber of items successfully read or written (that is, not the number of characters). If an error 
occurs, or the end-of-file is reached, the return value is a short iten count (or e). 


fread does not distinguish between end-of-file and error, and callers must use feot(3) and ferror(3) to determine which 
occurred. 


SEE ALSO 


feof(3), ferror(3), read(2), write(2) 


STANDARDS 
The functions fread and fwrite conform to AN SI C3.159-1989 (“AN SIC”), 
BSD Man Page 17 M ay 1996 


frexp 


frexp— Converts floating-point number to fractional and integral components 


SYNOPSIS 


#include <math.h> 
double frexp(double x, int *exp); 


DESCRIPTION 


The frexp() function is used to split the number x into anormdized fraction and an exponent that is stored in exp. 


RETURN VALUE 


The frexp() function returns the normalized fraction. If the argument x isnot ea, the normalized fraction isx times a power 
of 2, and is alwaysin the range % (inclusive) to 1 (exclusive). If x is@, the normalized fraction is 0, and 0 isstored in exp. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
1dexp(3), modf(3) 
GNU, 6 June1993 


fgetpos, fseek, fsetpos, ftell, rewind 


fgetpos, fseek, fsetpos, ftell, rewind— Reposition a stream 


Part III: Library Functions 


SYNOPSIS 


#include <stdio.h> 

int fseek(FILE *stream, longo ffset, int whence); 
long ftell(FILE *stream); 
void rewind(FILE *stream); 
int fgetpos(FILE *stream, fpos_t *pos); 
int fsetpos(FILE *stream, fpos_t *pos); 


DESCRIPTION 


The fseek function sets the file position indicator for the stream pointed to by stream. The new position, measured in bytes, 
is obtained by adding offset bytes to the position specified by whence. If whence iSset to SEEK_SET, SEEK_CUR, OF SEEK_END, the 
offset is relative to the start of the file, the current position indicator, or end-of-file, respectively. A successful call to the tseek 
function clears the end-of-file indicator for the stream and undoes any effects of the ungetc(3) function on the same stream. 





The fte11 function obtains the current value of the file position indicator for the stream pointed to by stream. 


The rewind function sets the file position indicator for the stream pointed to by stream to the beginning of thefile It is 
equivalent to 


(void)fseek(stream, OL, SEEK_SET); 
except that the error indicator for the stream is also cleared. (See clearerr(3).) 


The fgetpos and fsetpos functions are alternate interfaces equivalent to fte11 and fseek (with whence Set to SEEK SET), setting 
and storing the current value of the file offset into or from the object referenced by pos. On somenon-UN IX systems, an 
fpos_t object may be a complex object, and these routines might be the only way to portably reposition atext stream. 


RETURN VALUES 


The rewind function returns no value. Upon successful completion, fgetpos, fseek, and fsetpos return a, and ftel1 re€turns 
the current offset. O therwise, -1 is returned, and the global variable errno is set to indicate the error. 


ERRORS 
EBADF The stream specified is not a seekable stream. 
EINVAL The whence argument to fseek was not SEEK_SET, SEEK_END, OF SEEK_CUR. 


The function fgetpos, fseek, fsetpos, and ftel1 might also fail and set errno for any of the errors specified for the routines 
fflush(3), fstat(2), 1seek(2), aNd malloc(3). 


SEE ALSO 


lseek(2) 


STANDARDS 


The fgetpos, fsetpos, fseek, ftell, and rewind functions conform to AN SI C3.159-1989 (ANSI C), 
BSD Man Page, 29 November 1993 


ftime 


ftime— Returns date and time 


SYNOPSIS 


#include <sys/timeb.h> 
int ftime(struct timeb *tp); 


ftok 


DESCRIPTION 
Return current date and timeintp, which is declared as follows: 


struct timeb { 
time_t time; 
unsigned short millitm; 
short timezone; 
short dstflag; 
}; 
RETURN VALUE 


This function always returns 0. 


NOTES 
Under Linux, this function is implemented in a compatibility library instead of in the kernel. 
CONFORMS TO 
Version 7, BSD 4.3 
Unde BSD 4.3, this call is obsoleted by gettimeofday(2). 
SEE ALSO 
time(2) 
Linux, 24 July 1993 


ftok 


ftok— Converts a pathname and a project identifier to a Systen V IPC key 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/ipc.h> 
key_t ftok (char *pathname, char proj); 


DESCRIPTION 


The function converts the pathname of an existing accessible file and a project identifier into a key_t type System V IPC key. 


RETURN VALUE 


On success, the return value will be the converted key_t value; otherwise it will be-1, with errno indicating the error as for 
the stat(2) system call. 


BUGS 


The generated key _t value is obtained by stating the disk file corresponding to pat hname in order to get its i-node number 
and the minor device number of the filesystem on which the disk file resides, then by combining the 8-bit proj value along 
with the lower 16 bits of the inode number with the 8 bits of the minor device number. T he algorithm does not guarantee a 
unique key value. In fact, 


m Two different nameslinking to the same file produce the same key values. 

m Using the lower 16 bits of the i-node number gives some chance (although usually small) to have the same key values 
for filarames referring to different inodes. 

m Not discriminating among major device numbers gives some chance of collision (also usually small) for systems with 
multiple disk controllers. 


Part III: Library Functions 


SEE ALSO 


ipc(5), msgget(2), semget(2), shmget(2), stat(2) 
Linux 0.99.13, 1 November 1993 


ftw 


ftw— File tree walk 


SYNOPSIS 


#include <ftw.h> 
int ftw(const char *directory, 
int(*funcptr)(const char *file, struct stat *sb, int flag), int depth); 


DESCRIPTION 


ftw() walks through the directory tree, starting from theindicated direct ory. For each found entry in the tree, it callsfuncptr 
with the full pathname of the entry relative to directory, a pointer to the stat(2) structure for the entry and an int whose 
value will be one of the following: 


FTW_F Item isanormal file 

FTW_D Item is a directory 

FTW_NS The stat failed on the item 

FTW_DNR Item is a directory which can’t be read 


Warning: Anything other than directories, such as symbolic links, gets the FTw_F tag. 


ftw() recursively calls itself for traversing found directories. To avoid using up all a program’s file descriptors, depth specifies 
the number of simultaneous open directories. W hen the depth is exceeded, ftw) will become slower because directories have 
to be closed and reopened. 


To stop the tree walk, funcptr returns anonzero value; this value will become the return value of ftp(). Otherwise, ftw() will 
continue until it has traversed the entire tree (in which caseit will return o), or until it hits an error such as amalloc(3) 
failure, in which case it will return -1. 


Because ftp() uses dynamic data structures, the only safe way to exit a tree walk is to return a nonzero value. To handle 
interrupts, for example, mark that the interrupt occurred and return a nonzero value— don’t use 1ongjmp(3) unless the 
program is going to teminate. 


SEE ALSO 
stat(2) 
Linux, 18 July 1993 


gcevt 


gevt— Convets a floating-point number to a string 


SYNOPSIS 


#include <stdlib.h> 
char *gcvt(double number, size t ndigit, char *buf); 


DESCRIPTION 


The gevt() function converts number to aminimal-length, NULL-terminated ASCII string and stores the result in buf. It 
produces ndi git significant digits in either printt() F format or E format. 


getdirentries 


RETURN VALUE 
The gevt() function returns the address of the string pointed to by but. 


SEE ALSO 
ecvt(3), fevt(3), sprintf(3) 
29 M arch 1993 


getcwd, get_current_dir_name, getwd 


getcwd, get_current_dir_name, getwd— Get current working directory 


SYNOPSIS 


#include <unistd.h> 

char *getcwd(char *buf, size_t size); 
char *get_current_working dir_name(void) ; 
char *getwd(char *buf ); 


DESCRIPTION 


The getcwd() function copies the absolute pathname of the current working directory to the array pointed to by buf , which is 
of length size. 


If the current absolute pathname would require a buffer longer than size elements, nuLL is returned, and errno is set to 
ERANGE; an application should check for thiserror, and allocate a larger buffer if necessary. 


Asan extension to the PO SIX.1 standard, getewd() allocates the buffer dynamically using malloc() if buf iSNULL On call. In 
this case, the allocated buffer has the length size unlesssize isless than 0, when but isallocated as large as necessary. It is 
possible (and, indeed, advisable) to free the buffers if they have been obtained this way. 


get_current_dir_name, which isonly prototyped if __use_anu is defined, will mal1oc(3) an array big enough to hold the 
current directory name. If the environment variable pwo is set, and its value is correct, that value will be returned. 


getwa, which is only prototyped if _ use_ssp is defined, will not mal1oc(3) any memory. Thebuf argument should bea 
pointer to an array at least PATH_mAX bytes long. getwd returns only the first PatH_MAX bytes of the actual pathname. 


RETURN VALUE 


NULL On failure (for example, if the current directory is not readable), with errno set accordingly, and buf on success. 


CONFORMS TO 
POSIX.1 


SEE ALSO 
chdir(2), free(3), malloc(3). 
GNU, 21 July1993 


getdirentries 


getdirentries— Gets directory entries in a filesystem-indeoendent format 


#define _ USE_BSD or #define _ USE_MISC 
#include <dirent.h> 
ssize_t getdirentries(int fd, char *buf, size_t nbytes ,offt *basep); 


Part III: Library Functions 


DESCRIPTION 


This function reads directory entriesfrom the directory specified by fd into buf. At most, nbytes are read. Reading starts at 
offset *basep, and *basep isupdated with the new position after reading. 


RETURN VALUE 


getdirentries returns thenumber of bytes read, or o when at the end of thedirectory. If an error occurs, -1 is returned, and 
errno is set appropriately. 


ERRORS 


See the Linux library source code for details. 
SEE ALSO 
open(2), 1seek(2) 
BSD/MISC, 22 July 1993 


getenv 


getenv— Gets an environment variable 


SYNOPSIS 


#include <stdlib.h> 
char *getenv(const char *name); 


DESCRIPTION 


The getenv() function searches the environment list for a string that matches the string pointed to byname. T he strings are of 
the form name=val ue. 


RETURN VALUE 


The getenv() function returns a pointer to the value in the environment, or NuLL if there isno match. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


putenv(3), setenv(3), unsetenv(3) 
GNU, 3 April 1993 


getgrent, setgrent, endgrent 


getgrent, setgrent, endgrent— Get group file entry 


SYNOPSIS 


#include <grp.h> 

#include <sys/types.h> 
struct group *getgrent(void) ; 
void setgrent (void) ; 

void endgrent (void) ; 


getgrnam, getgrgid 
DESCRIPTION 


The getgrent() function returns a pointer to a structure containing the group information from /etc/group. T he first time it 
is called it returns the first entry; thereafter, it returns successive entries. 


The setgrent() function rewinds the file pointer to the beginning of the /etc/group file. 
The endgrent() function closes the /etc/group file 
The group structure is defined in <grp.h> as follows: 


struct group { 


char *gr_name; /* group name */ 
char *gr_passwd; /* group password */ 
gid_t gr_gid; /* group id */ 
char **gr_mem; /* group members */ 
hs 
RETURN VALUE 
The getgrent() function returns the group information structure, or NULL if there areno more entries or an error occurs. 
ERRORS 
ENOMEM Insufficient memory to allocate group information structure. 
FILES 
/etc/group group database file 
CONFORMS TO 
SVID 3, BSD 4.3 
SEE ALSO 


fgetgrent(3), getgrnam(3), getgrgid(3) 
GNU, 4 April 1993 


getgrnam, getgrgid 


getgrnam, getgrgid— Ge group file try 


SYNOPSIS 


#include <grp.h> 

#include <sys/types.h> 

struct group *getgrnam(const char *name); 
struct group *getgrgid(gid t gid); 


DESCRIPTION 


The getgrnam() function returns a pointer to a structure containing the group information from /etc/group for the entry that 
matches the group namename. 


The getgrgid() function returns a pointer to a structure containing the group information from /etc/group for the entry that 
matches the group id gid. 


The group structure is defined in <grp.h> as follows: 


struct group { 
char *gr_name; /* group name */ 
char *gr_passwd; /* group password */ 
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gid_t gr_gid; /* group id */ 
char **gr_mem; /* group members */ 
}; 
RETURN VALUE 


The getgrnam()and getgrgid() functions return the group information structure, or NuLL if the matching entry is not found 
or an error occurs. 


ERRORS 


ENOMEM Insufficient memory to allocate group information structure. 


FILES 


/etc/group group database file 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3 


SEE ALSO 


fgetgrent(3), getgrent(3), setgrent(3), endgrent(3) 
GNU, 4 April 1993 


getlogin, cuserid 


getlogin, cuserid— Get username 


SYNOPSIS 
#include <unistd.h> 
char * getlogin ( void ); 
#include <stdio.h> 
char * cuserid ( char *string ); 


DESCRIPTION 


getlogin returnsa pointer to a string containing the name of the user logged in on the controlling terminal of the process, or 
anull pointer if thisinformation cannot be determined. T he string is statically allocated and might be overwritten on 
subsequent calls to this function or to cuserid. 


cuserid returns a pointer to a string containing ausername associated with the effective user 1D of the process. If string is 
not anull pointer, it should be an array that can hold at least L_cuserid characters; the string is returned in this array. 
Otherwise, a pointer to astring in a static area is returned. This string is statically allocated and might be overwritten on 
subsequent calls to this function or to getlogin. 


The macro t_cuserid is an integer constant that indicates how long an array you might need to store a username. L_cuserid iS 
declared in stdio.h. 


These functions le your program positivey identify the user who is running (cuserid) or the user who logged in this session 
(getlogin). (T hese can differ when setuid programs are involved.) The user cannot do anything to fool these functions. 


For most purposes, it ismore useful to use the environment variable Locname to find out who the user is. This ismore flexible 
precisely because the user can set Loaname arbitrarily. 


ERRORS 


ENOMEM Insufficient memory to allocate passwd structure 


gemntent, stmntent, addmntent, endmntent, hasmntopt 
FILES 


The /etc/passwd password database file /etc/utmp (Or /var/adm/utmp, or wherever your utmp file lives these days— the proper 
location depends on your libc version) 


CONFORMS TO 
POSIX.1. System V has a cuserid function that uses the real user 1D rather than the effective user 1D. The cuserid function 
was included in the 1988 version of POSIX, but was renoved from the 1990 version. 


BUGS 


Unfortunately, it is often rather easy to fool getlogin(). Sometimes it does not work at all, because some program messed up 
the utmp file O ften, it gives only thefirst eight characters of the login name. The user currently logged in on the controlling 
tty of your program need not be the user who started it. 


N obody knows precisely what cuserid() does; so 


m@ Avoid it in portable programs 
m Avoid it altogether 
M@ Usegetpwuid (geteuid()) instead, if that is what you meant. 


Simply, do not us%cuserid(). 


SEE ALSO 


geteuid(2), getuid(2) 


Linux 1.2.13, 3 Septenber 1995 


getmntent, setmntent, addmntent, endmntent, hasmntopt 


getmntent, setmntent, addmntent, endmntent, hasmntopt— Gat filesystem descriptor file entry 


SYNOPSIS 


#include <stdio.h> 

#include <mntent.h> 

FILE *setmntent(const char *filep, const char *ty 
struct mntent *getmntent(FILE *filep); 

int addmntent(FILE *filep, const struct mntent *mnt ); 
int endmntent(FILE *filep); 
char *hasmntopt(const struct mntent *mnt, const char *opt ); 


DESCRIPTION 


T hese routines are used to access the filesystem description file /etc/fstab and the mounted filesystem description file /etc/ 
mstab. 


o 


3 





The setmntent() function opens the filesystem description filefil!ep and returns a file pointer that can be used by 
getmntent(). Theargument type isthe type of access required and can take the same values as the mode argument of fopen(3). 


The getmntent() function reads the next line from the filesystem description filefil! ep and returns a pointer to a structure 
containing the broken-out fidds from alinein the file The pointer points to a static area of memory that is overwritten by 
subsequent calls to getmntent(). 


The addmntent() function adds the mntent structure mit to the end of the open file filep. 
The endmntent() function closes the filesystan description filefi ep. 














The hasmntopt() function scans the mt opts field of the mntent structure mt for a substring that matches opt . (See 
<mntent.h> for valid mount options.) 
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Themntent structure is defined in <mntent.h> as follows: 


struct mntent { 


char *mnt_fsname; /* name of mounted filesystem */ 
char *mnt_dir; /* filesystem path prefix */ 

char *mnt_type; /* mount type (see mntent.h) */ 
char *mnt_opts; /* mount options (see mntent.h) */ 
int mnt_freq; /* dump frequency in days */ 

int mnt_passno; /* pass number on parallel fsck */ 

}; 
RETURN VALUE 


The getmntent() function returns a pointer to themntent structure or NULL on failure. 

The addmntent() function returns on success and 1 on failure 

The endmntent() functions always returns 1. 

The hasmntopt() function returns the address of the substring if a match isfound, and NnuLL otherwise. 


FILES 
/etc/fstab filesystem description file 
/etc/mtab mounted filesystem description file 


CONFORMS TO 
BSD 4.3 


SEE ALSO 
fopen(3), fstab(5) 
27 June1993 


getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent 


getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent— Get network entry 


SYNTAX 


#include <netdb.h> 

struct netent *getnetent() 

struct netent *getnetbyname (name ) 

char *name; 

struct netent *getnetbyaddr(net, type) 
long net ; int type; 

void setnetent(stayopen) 

int stayopen; 

void endnetent() 


DESCRIPTION 


The getnetent, getnetbyname, aNd getnetbyaddr Subroutines each return a pointer to an object with the following structure, 
containing the broken-out fidds of alinein the network database, /etc/networks: 


struct netent { 


char *n_name; /* official name of net */ 
char **n aliases; /* alias list */ 

int n_addrtype; /* net number type */ 

long n_net; /* net number */ 


}; 
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The members of this structure are 


n_name The official name of the network. 

n_aliases A zero-terminated list of alternate names for the network. 

n_addrtype The type of the network number returned: AF_INET. 

n_net The network number. N etwork numbers are returned in machine byte order. 


If the st ayopen flag on asetnetent subroutine is NuLL, the network database is opened. O therwise the setnetent has the effect 
of rewinding the network database The endnetent may be called to close the network database when processing is complete. 


The getnetent subroutine simply reads the next line whereas getnetbyname and getnetbyaddr search until a matching name or 
net Number is found (or until EoF is encountered). Thetype must be AF_INET. T he getnetent Subroutine keeps a pointer in 
the database, allowing successive calls to be used to search the entire file. 


A call to setnetent must be made before a while loop using getnetent to perform initialization, and an endnetent must be 
used after the loop. Both getnetbyname and getnetbyaddr make calls to setnetent and endnetent. 


FILES 


/etc/networks 


DIAGNOSTICS 


N ull pointer (0) returned on Eor or error. 


SEE ALSO 
networks(5), RFC 1101 


HISTORY 


The getnetent(), getnetbyaddr(), Getnetbyname(), setnetent(), aNd endnetent() functions appeared in 4.2BSD. 


BUGS 


The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls 
to these functions overwrite it. O nly Internet network numbers are currently understood. Expecting network numbers to fit 
in no more than 32 bits is probably naive 
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getopt— Parses command-line options 


SYNOPSIS 


#include <unistd.h> 

int getopt(int argc, char * const argv[], 
const char *optstring); 

extern char *optarg; 

extern int optind, opterr, optopt; 

#include <getopt.h> 

int getopt_long(int argc, char * const argv[], 


const char *optstring, 
const struct option *longopts, int *l ongindex); 
int getopt_long_only(int argc, char * const argv[], 





const char *optstring, 
const struct option *longopts, int *longindex); 
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DESCRIPTION 


The getopt() function parses the command-line arguments. Its arguments argc and argv are the argument count and array as 
passed to the main() function on program invocation. An elanent of argv that starts with - (and isnot exactly - or --) isan 
option element. The characters of this dement (aside from the initial -) are option characters. If getopt() is called repeatedly, 
it returns successively each of the option characters from each of the option elements. 


If getopt() finds another option character, it returns that character, updating the external variable opti nd and a static variable 
nextchar So that the next call to getopt() can resume the scan with the following option character or argv @enent. 


If there are no more option characters, getopt() returns Eor. Then optind isthe index in argv of the first argv Aement that is 
not an option. 


optstring iSa string containing the legitimate option characters. If such a character is followed by acolon, the option 
requires an argument, So getopt placesa pointer to the following text in thesameargv element, or the text of the following 
argv Aeament, in opt arg. T wo colons mean an option takes an optional arg; if there is text in the current argv dement, it is 
returned in optarg; otherwise, optarg is set to o. 


By default, getargs() permutes the contents of argv asit scans, so that eventually all the non-options are at the end. T wo 
othe modes are also implemented. If the first character of optstring is + or the environment variable posrxLy_corRECT is set, 
option processing stops as soon as anon-option argument is encountered. If the first character of optstring is -, each non- 
option argv Aenent is handled asif it were the argument of an option with character code 1. (This is used by programs that 
were written to expect options and other argv elementsin any order and that care about the ordering of the two.) The special 
argument - forces an end of option-scanning regardless of the scanning mode. 


If getopt() does not recognize an option character, it prints an error message to stderr, stores the character in optopt, and 
returns?. T he calling program may prevent the error message by setting opterr to a. 


The getopt_1ong()function works like getopt(), except that it also accepts long options, started out by two dashes. Long 
option names may be abbreviated if the abbreviation is unique or is an exact match for some defined option. A long option 
may take a parameter, of the form --arg=param Or --arg param. 


longopts iSapointer to the first denent of an array of struct option declared in <getopt.h>: 


as struct option { 
const char *name; 
int has_arg; 
int *flag; 
int val ; 

}; 


The meanings of the different fidds are 


name Thename of thelong option. 

has_arg no_argument (or 0) if the option does not take an argument, required_argument (or 1) if the 
option requires an argument, or optional_argument (or 2) if the option takes an optional 
argument. 

flag Specifies how results are returned for along option. If flag iSNULL, getopt_long() returnsval . 


(For example the calling program might set val to the equivalent short option character.) 
Otherwise, getopt_long() returns, and f! ag points to a variable that is set to val if theoption 
is found, but left unchanged if the option is not found. 


val The value to return or to load into the variable pointed to byt! ag. 
Thelast element of the array hasto be filled with zeroes. 
If | ongindex iSnot NULL, it points to a variable that is set to the index of the long option relative to | ongopts. 


getopt_long_only() iSlike getopt_long(), but - as well as -- can indicate along option. If an option that starts with - (not --) 
doesn’t match along option but does match a short option, it is parsed as a short option instead. 


RETURN VALUE 


The getopt()function returns the option character if the option was found successfully, : if there was a missing parameter for 


one of the options, ? for an unknown option character, or Eor for the end of the option list. 


getopt_long() and getopt_long_only() also return the option character when a short option is recognized. For along option, 
they return val iffiag iSNULL, and @ otherwise Error and cor returns are the same as for getopt(), plus ? for an ambiguous 


match or an extraneous parameter. 


ENVIRONMENT VARIABLES 


POSIXLY_CORRECT If this is set, option processing stops as soon as anon-option argument is encountered. 


EXAMPLE 


The following example program, from the source code, illustrates the use of getopt_long() with most of its features: 


#include <stdio.h> 
int 
main (argc, argv) 
int argc; 
char **argv; 


int c; 

int digit_optind = Q; 
while (1) 

{ 


int this_option_optind = optind ? optind : 


int option_index = Q; 
static struct option | ong_options[] 
{ 

{"add", 1, 0, O}, 

{"append", 0, 0, 0}, 

{"delete", 1, 0, 0}, 

{"verbose", 0, 0, 0}, 

{"create", 1, 0, 'c'}, 

{"file", 1, 0, 0g, f0, 0, 0, 0} 
}; 


C = getopt_long (argc, argv, "“abco:d:012" 


long_options, &option index); 
if (c == -1) 

break; 
switch(c ) 
{ 

case 0: 


printf ("option %s", |ong_options[option_index].name); 


if (optarg) 


printf (" with arg %s", optarg); 


printf ("\n"); 
break; 

case 'Q': 

case '1': 

case '2': 


if (digit_optind != @ && digit_optind 


!= this option _optind) 


printf ("digits occur in two different argv-elements.\n"); 


digit_optind = this_option_optind; 


printf ("option %c\n", c); 
break; 

case ‘a': 
printf ("option a\n"); 
break; 

case 'b': 
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printf ("option b\n"); 
break; 
case 'C': 
printf ("option c with value '%s'\n", optarg); 
break; 
case ‘d': 
printf ("option d with value '%s' \n", optarg); 
break; 
case '?': 
break; 
default: 
printf ("?? getopt returned character code 0%0 ??\n", c); 
} 
} 
if (optind < argc) 
{ 
printf ("non-option ARGV-elements: "); 
while (optind < argc) 
printf ("%s ", argv[optind++] ); 
printf ("\n"); 





} 
exit (Q); 
} 
BUGS 
This man page is confusing. 
CONFORMS TO 
getopt(): POSIX.1, provided the environment variable posrxLy_correcT isset. Otherwise, the elements of argv aren't 
really const, because they get permuted. They're set const in the prototype to be compatible with other 
systems. 


GNU, 30 Augut 1995 


getpass 
getpass— Gets a password 


SYNOPSIS 


#include <pwd.h> 
#include <unistd.h> 
char *getpass( const char * prompt ); 


DESCRIPTION 


The getpass function displays a prompt to, and readsin, apassword from, /dev/tty. If this fileis not accessible, getpass 
displays the prompt on the standard error output and reads from the standard input. 


The password may be up to _PAssworD_LEN (currently 128) characters in length. Any additional characters and the terminat- 
ing newline character are discarded. (This might be different in Linux.) 


getpass turns off character echoing while reading the password. 


RETURN VALUES 


getpass returns a pointer to the null-terminated password. 


getprotoent, getprotobyname getprotobynumber, setprotoent, endprotoet 


FILES 


/dev/tty 


SEE ALSO 


crypt(3) 


HISTORY 
A getpass function appeared in Version 7 AT&T UNIX. 


BUGS 


The getpass function leaves its result in an internal static object and returns a pointer to that object. Subsequent calls to 
getpass will modify the same object. 


The calling process should zero the password as soon as possible to avoid leaving the cleartext password visible in the 
process's address space. 


BSD Man Page29 N ovenber 1993 


getprotoent, getprotobyname, getprotobynumber, setprotoent, 
endprotoent 


getprotoent, getprotobyname, getprotobynumber, setprotoent, endprotoent— Get protocol entry 


SYNOPSIS 


#include <netdb.h> 

struct protoent *getprotoent (void) ; 

struct protoent *getprotobyname(const char *name); 
struct protoent *getprotobynumber(int proto); 

void setprotoent(int stayopen); 

void endprotoent(void) ; 


DESCRIPTION 


The getprotoent() function reads the next line from the file /etc/protocols and returns a structure prot oent containing the 
broken-out fields from the line The /etc/protocols file is opened if necessary. 


The getprotobyname() function returns aprotoent structure for the line from /etc/protocols that matches the protocol name 
name. 


The getprotobynumber() function returns aprotoent structure for the line that matches the protocol number number. 


The setprotoent() function opens and rewindsthe /etc/protocols file If stayopen istrue(1), thefile will not be closed 
between calls to getprotobyname() OF getprotobynumber(). 


The@endprotoent() function closes /etc/protocols. 
The protoent structure is defined in <netdb.h> as follows: 


struct protoent { 
char *p_name; /* official protocol name */ 
char **p aliases; /* alias list */ 
int p_proto; /* protocol number */ 
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The members of the protoent structure are 


p_name The official name of the protocol. 
p_aliases A zero-terminated list of alternative names for the protocol. 
p_proto The protocol number. 

RETURN VALUE 


The getprotoent(), getprotobyname(), aNd getprotobynumber() functions return theprotoent structure, or aNULL pointer if an 
error occurs or the end of the file is reached. 


FILES 


/etc/protocols protocol database file 


CONFORMS TO 
BSD 4.3 


SEE ALSO 


getservent(3), getnetent(3), protocols(5) 
BSD, 24 April 1993 


getpw 


getpw— Reconstructs password line entry 


SYNOPSIS 


#include <pwd.h> 
#include <sys/types.h> 
int getpw(uid_t uid, char *buf ); 


DESCRIPTION 


The getpw() function reconstructs the password line entry for the given user UID uid in the buffer buf . The returned buffer 
contains a line of format 


name: passwd: uid:gid:gecos:dir:shell 
The passwd structure is defined in <pwd.h> as follows: 


struct passwd { 


char *pw_name; /*username* / 
char *pw_passwd; /* user password */ 
uid_t pw_uid; /* user id */ 
gid t pw_gid; /* group id */ 
char *pw_gecos; /* real name */ 
char *pw_dir; /* home directory */ 
char *pw_shell; /* shell program */ 

}; 

RETURN VALUE 
The getpw()function returns @ on success, or -1 if an error occurs. 


ERRORS 


ENOMEM Insufficient memory to allocate passwd structure. 


getpwent, setowent, endpwent 


FILES 


/etc/passwd Password database file 


SEE ALSO 


fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), putpwent(3), passwd(5) 
GNU, 27 May 1996 


getpwent, setpwent, endpwent 


getpwent, setpwent, endpwent— get password file entry 


SYNOPSIS 


#include <pwd.h> 

#include <sys/types.h> 

struct passwd *getpwent (void) ; 
void setpwent (void) ; 

void endpwent (void) ; 


DESCRIPTION 


The getpwent() function returns a pointer to a structure containing the broken-out fields of aline from /etc/passwd. T he 
first timeit is called it returns the first entry; thereafter, it returns successive entries. 


The setpwent() function rewinds the file pointer to the beginning of the /etc/passud file 
The endpwent() function closes the /etc/passwd file. 
The passwd structure is defined in <pwd.h> as follows: 


struct passwd { 


char *pw_name; /*username* / 
char *pw_passwd; /* user password */ 
uid_t pw_uid; /* user id */ 
gid_t pw_gid; /* group id */ 
char *pw_gecos; /* real name */ 
char *pw_dir; /* home directory */ 
char *pw_shell; /* shell program */ 
hs 
RETURN VALUE 
The getpwent()function returns the passwd structure, or NULL if there areno more entries or an error occurs. 
ERRORS 
ENOMEM Insufficient memory to allocate passwd structure 
FILES 
/etc/passwd Password database file 
CONFORMS TO 
SVID 3, BSD 4.3 
SEE ALSO 


fgetpwent(3), getpwnam(3), getpwuid(3), getpw(3), putpwent(3), passwa(5), 
GNU, 27 May 1996 
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getpwnam, getpwuid 


getpwnam, getpwuid— Get password file entry 


SYNOPSIS 


#include <pwd.h> 

#include <sys/types.h> 

struct passwd *getpwnam(const char * name); 
struct passwd *getpwuid(uid_t uid); 


DESCRIPTION 


The getpwnam() function returns a pointer to a structure containing the broken out fields of aline from /etc/passwd for the 
entry that matches the username name. 


The getpwuid() function returns a pointer to a structure containing the broken-out fields of aline from /etc/passwa for the 
entry that matches the user UID uid. 


The passwd structure is defined in <pwd.h> as follows: 


struct passwd { 


char *pw_name; /*username* / 

char *pw_passwd; /* user password */ 
uid_t pw_uid; /* user id */ 

gid_t pw_gid; /* group id */ 

char *pw_gecos; /* real name */ 
char *pw_dir; /* home directory */ 


char *pw_shell; /* shell program */ 
}; 


RETURN VALUE 


The getpwnam()and getpwuid() functions return the passwd structure, or NULL if the matching entry is not found or an error 
occurs. 


ERRORS 


ENOMEM Insufficient memory to allocate passwd structure 


FILES 


/etc/passwd Password database file 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3 


SEE ALSO 


fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwent(3), passwa(5) 
GNU, 27 May 1996 


fgetc, fgets, getc, getchar, gets, ungetc 


fgetc, fgets, getc, getchar, gets, ungetc— Input of characters and strings 


SYNOPSIS 


#include <stdio.h> 
int fgetc(FILE *stream); 
char *fgets(char *s,int size, FILE *stream); 


getsarvent, getservbyname, getsarvbyport, setsarvent, endsarvent 


int getc(FILE *stream); 

int getchar(void) ; 

char *gets(char *s); 

int ungetc(int c, FILE *stream); 


DESCRIPTION 
fgetc() reads the next character from stream and returnsit aS an unsigned char cast to an int, or EoF on end of file or error. 
getc() iS equivalent to fgetc() except that it can beimplemented as a macro that evaluates stream more than once 
getchar() iS equivalent to getc(stdin). 


gets()reads a line from stdin into the buffer pointed to bys until either a terminating newline or EOF, which it replaces 
with \o. No check for buffer overrun is performed (see the following “Bus” section). 


fgets() reads in at most one less than n characters from stream and stores then into the buffer pointed to bys. Reading stops 
after an Eor or anewline If anewlineis read, it is stored into the buffer. \a is stored after the last character in the buffer. 


ungetc() pushesc back to stream, Cast to unsigned char, whereit is available for subsequent read operations. Pushed-back 
characters will be returned in reverse order; only onepushback is guaranteed. 


Calls to the functions described here can be mixed with each other and with calls to other input functions from the stdio 
library for the same input stream. 

RETURN VALUES 
fgetc(), getc(), aNd getchar() return the character read as an unsigned char cast to an int, or EoF on end of file or error. 
gets() and fgets() return s on SUCCéss, and NULL On error or when end of file occurs while no characters have been read. 
ungetc() returnSc On SUCCESS, OF EOF ON error. 


CONFORMS TO 
ANSI-C, POSIX.1 
BUGS 


Because it is impossible to tell without knowing the data in advance how many characters gets() will read, and because 
gets() will continue to store characters past the end of the buffer, it is extremay dangerous to use. It has been used to break 
computer security. U se fgets() instead. 


It is not advisable to mix calls to input functions from the stdio library with low-level calls to read() for the file descriptor 
associated with the input stream; the results will be undefined and very probably not what you want. 


SEE ALSO 
read(2), write(2), fopen(3), fread(3), scant(3), puts(3), fseek(3), ferror(3) 
GNU, 4 April 1993 


getservent, getservbyname, getservbyport, setservent, 
endservent 


getservent, getservbyname, getservbyport, setservent, endservent— Get service entry 


SYNOPSIS 


#include <netdb.h> 

struct servent *getservent(void) ; 

struct servent *getservbyname(const char *name, const char *proto); 
struct servent *getservbyport(int port, const char *proto); 
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void setservent(int stayopen); 
void endservent (void) ; 


DESCRIPTION 


The getservent() function reads the next line from thefile /etc/services and returns a structure, servent , containing the 
broken out fields from the line The /etc/services file is opened if necessary. 


The getservbyname()function returns aservent structure for the line from /etc/services that matches the service name using 
protocol proto. 


The getservbyport()function returns aservent structure for the line that matches the port port given in network byte order 
using protocol proto. 


The setservent() function opens and rewinds the /etc/services file. If stayopen istrue (1), the file will not be closed between 
Calls to getservbyname() and getservbyport(). 


The endservent() function closes /etc/services. 
Theservent structure is defined in <netdb.h> as follows: 


struct servent { 

char *s_name; /* official service name */ 
char **s_ aliases; /* alias list */ 

int s_port; /* port number */ 

char *s_proto; /* protocol to use */ 

} 


Themembers of theservent structure are: 


s_name The official name of the service. 
s_aliases A zero-terminated list of alternative names for the service. 
s_port The port number for the service, given in network byte order. 
s_proto Thename of the protocol to use with this service. 

RETURN VALUE 


The getservent(), getservbyname(), and getservbyport() functions return theservent structure or a NULL pointer if an error 
occurs or the end of thefile is reached. 


FILES 


/etc/services  Servicesdatabase file 


CONFORMS T0 
BSD 4.3 


SEE ALSO 


getprotoent(3), getnetent(3), services(5) 
BSD, 22 April 1996 


getusershell, setusershell, endusershell 


getusershell, setusershell, endusershell— Get legal user shells 


SYNOPSIS 


#include <unistd.h> 
char *getusershell(void) ; 
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void setusershell(void); 
void endusershell(void) ; 


DESCRIPTION 


The getusershe11() function returns the next line from thefile /etc/shells, opening the file if necessary. T he line should 
contain the pathname of a valid user shal. If /etc/shel1s does not exist or is unreadable, getusershell() behaves as if /bin/sh 
and /bin/csh were listed in the file. 


The setusershell() function rewinds /etc/shells. 
The endusershell() function closes /etc/shells. 


RETURN VALUE 


The getusershe11() function returns aN ULL pointer on end of file 


FILES 


/etc/shells 


CONFORMS TO 
BSD 4.3 


SEE ALSO 


shells(5) 








BSD, 4 July1993 


getutent, getutid, getutline, pututline, setutent, endutent, 
utmpname 


getutent, getutid, getutline, pututline, setutent, endutent, utmpname— ACCess utmp file entries 


SYNOPSIS 


#include <utmp.h> 

struct utmp *getutent (void) ; 

struct utmp *getutid(struct utmp *ut ); 
struct utmp *getutline(struct utmp *ut); 
void pututline(struct utmp *ut); 

void setutent (void) ; 

void endutent (void) ; 

void utmpname(const char *file); 


DESCRIPTION 


utmpname() sets the name of the utmp-format file for the other utmp functions to access. If utmpname() isnot used to set the 
filename before the other functions are used, they assume PATH_UTMP, aS defined in <paths.h>. 


setutent() rewinds the file pointer to the beginning of theutmp file It is generally a good idea to call it before any of the 
othe functions. 


endutent()Closesthe utmp file It should be called when the user code is done accessing the file with the other functions. 


getutent() readsalinefrom the current file position in the utmp file. It returns a pointer to a structure containing the fields 
of the line 





getutid() searches forward from the current file position in the utmp file based on ut . If ut ->ut_type iS RUN_LVL, BOOT_TIME, 
NEW TIME, OF OLD TIME, getutid() will find the first entry whose ut_type fidd matchesut ->ut_type. If ut ->ut_type is 
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INIT_PROCESS, LOGIN PROCESS, USER_PROCESS, OF DEAD_PROCESS, getutid() will find the first entry whose ut_ia field matches 
ut ->ut_id. 


getutline() searches forward from thecurrent file position in theutmp file It scans entries whoseut type is USER_PROCESS or 
LOGIN_PROcESS and returns the first one whose ut_line field matches ut ->ut_line. 


pututline()Wwrites the utmp structure ut into the utmp file. |t uses getutia() to search for the proper placein the file to insert 
the new entry. If it cannot find an appropriate slot for ut , pututline() will append the new entry to the end of the file. 


RETURN VALUE 


getutent(), getutid(), and getutline() return apointer to astruct utmp, which is defined in <utmp.h>. 
FILES 

/var/run/utmp— D atabase of currently logged-in users 

/var/1og/wtmp— D atabase of past user logins 


CONFORMS TO 
XPG 2, SVID 2, Linux FSSTN D 1.2 


SEE ALSO 


utmp(5) 
Linux libc 5.0.0, 22 March 1995 


getw, putw 


getw, putw— Input and output of words (ints) 


SYNOPSIS 


#include <stdio.h> 
int getw(FILE *stream); 
int putw(int w,FILE*stream); 


DESCRIPTION 


getw reads a word (that is, an int) from stream. It’s provided for compatibility with SVID. | recommend you use fread(3) 
instead. putw writes the word w (that is, an int) to stream. It is provided for compatibility with SVID, but | recommend you 
use fwrite(3) instead. 


RETURN VALUES 


Normally, getw returns the word read, and putw returns the word written. On error, they return cor. 


BUGS 


The value returned on error is also alegitimate data value. ferror(3) can beused to distinguish between the two cases. 


CONFORMS TO 
SVID 


SEE ALSO 


fread(3), fwrite(3), ferror(3), getc(3), putc(3) 
GNU, 16 Septenber 1995 


glob, globfree 


glob, globfree 


glob, globfree— Find pathnames matching a pattern; free memory from g1ob() 


SYNOPSIS 


#include <glob.h> 

int glob(const char *pattern, int flags, 

int errfunc (const char * epath, int eerrno), 
glob_t *pglob); 

void globfree(glob_t *pglob); 


DESCRIPTION 


The glob) function searches for all the pathnames matching pat t ern according to the rules used by the shell (see giob(7)). 
No tilde expansion or parameter substitution is done 


The globfree() function frees the dynamically allocated storage from an earlier call to giob(). 
The results of a glob() call are stored in the structure pointed to by pglob, which is aglob_t that is declared in <glob.h> as 


typedef struct 


{ 
int gl_pathc; /* Count of paths matched so far */ 
char **gl_pathv; /* List of matched pathnames. */ 
int gl_offs; /* Slots to reserve in ‘gl pathv'. */ 
int gl_flags; /* Flags for globbing */ 

} glob_t; 


Results are stored in dynamically allocated storage. 


The parameter fags ismade up of bitwise OR of zero or more the following symbolic constants, which modify the of 
behavior of glob(): 


GLOB_ERR Return on read error (because a directory does not have read permission, for example). 
GLOB_MARK Append aslash to each path which corresponds to a directory. 

GLOB_NOSORT Don’t sort the returned pathnames (they are by default). 

GLOB_DOOFS pglob->gl offs Slots will bereserved at the beginning of the list of strings in pgi ob ->pathv. 
GLOB_NOCHECK If no pattern matches, return the original pattern. 

GLOB_APPEND Append to the results of a previous call. D o not set this flag on the first invocation of glob(). 
GLOB_NOESCAPE M eta characters cannot be quoted by backslashes. 

GLOB_PERIOD A leading period can be matched by meta characters. 


If errfunc iS not NULL, it will be called in case of an error with the arguments epath, a pointer to the path that failed, and 
eerrno, the value of errno as returned from oneof the calls to opendir(), readdir(), Of stat().1f errfunc returns nonzero, or 
if GLoB_ERR iSset, glob() will terminate after the call to errfunc. 


Upon successful return, pgl ob ->gl_pathc contains the number of matched pathnames and pg! ob ->g!_pathv apointer to the 
list of matched pathnames. T he first pointer after the last pathname is NULL. 


It is possible to call glob() several times. In that case, the GLoB_aPPEND flag has to be set inf! ags on the second and later 
invocations. 

RETURN VALUES 
On successful completion, glob() returns. O ther possible returns are 


GLOB_NOSPACE For running out of memory, 
GLOB_ABEND For a read error, and 
GLOB_NOMATCH For no found matches. 
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EXAMPLES 
One example of use is the following code, which simulates typing in the shal: 
ls -1 *.¢ ../*.¢ 
glob_t globbuf; 
globbuf.gl_ offs = 2; 
glob("*.c", GLOB_DOOFS, NULL, &globbuf) ; 
glob("../*.c", GLOB_DOOFS | GLOB_ APPEND, NULL, &globbuf); 
globbuf.gl_pathv[0] = "ls"; 
globbuf.gl_pathv[1] = "-1"; 
execvp("1s", &globbuf.gl_pathv[]); 


CONFORMS TO 
Proposed PO SIX.2 


BUGS 


The glob()function may fail due to failure of underlying function calls, such aSmalloc() OF opendir(). T hese will store their 
error code in errno. 


POSIX.2 isnot ye an approved standard; the information in this man page is subject to change. 


SEE ALSO 
is(1), sh(1), exec(2), stat(2), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7) 
GNU, 13 May 1996 


hosts access, hosts ctl 


hosts_access, hosts_ctl— Access-control library functions 


SYNOPSIS 


#include "log _tcp.h" 

extern int allow severity; 
extern int deny severity; 

int hosts_access(daemon, client ) 
char *daemon ; 

struct client_info *client; 

int hosts_ctl(daemon, client_name, client_addr, client_user) 
char *daemon ; 

char *client_name; 

char *client_addr; 

char *client_user; 


DESCRIPTION 


The routines described in this document are part of the 1ibwrap.a library. T hey implement a pattern-based access-control 
anguage with optional shell commands that are executed when a pattern fires. 


In all cases, the daemon argument should specify a daemon process name (ar gv{ 0] value). The client host address should bea 
valid address, or FROM_UNKNoWN if the address lookup failed. The client hostname and username should be anpty strings if no 
information is available, FRom_unKNown if the lookup failed, or an actual hostname or username. 


hosts_access() Consults the access-control tables described in the hosts_access(5) manual page. hosts_access() returnso if 
access should be denied. 





hosts_ct1() iSa wrapper around the hosts_access() routine with a perhaps more convenient interface (although it does not 
pass on enough information to support automated renote username lookups). hosts_ct1() returns if access should be 
denied. 


hcreate, hdestroy, hsearch 


Theallow severity anddeny severity variables determine how accepted and rected requests can be logged. T hey must be 
provided by the caller and can be modified by rules in the access-control tables. 


DIAGNOSTICS 


Problems are reported viathe syslog daanon. 


SEE ALSO 


hosts_access(5) (format of the access control tables), hosts_options(5), optional extensions to the base language 


FILES 


/etc/hosts.access, /etc/hosts.deny access-control tables 


BUGS 
The functions described here do not make copies of their string-valued arguments. Beware of data from functions that 
overwrite ther results on each call. 


hosts_access() uses the strtok() library function. This may interfere with other code that rdies on strtok(). 


AUTHOR 
W ietse V enena (wietse@wzv.win. tue.nl) 
Department of M athenatics and Computing Science 
Eindhoven University of Technology 
Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The N etherlands 


hcreate, hdestroy, hsearch 


hcreate, hdestroy, hsearch— H ash table managenent 


SYNOPSIS 


#include <search.h> 

ENTRY *hsearch(ENTRY item, ACTION action); 
int hcreate(unsigned nel ); 

void hdestroy(void); 


DESCRIPTION 
T hese three functions allow the user to create a hash table that associates a key with any data. 


First, the table must be created with the function hcreate(). ne! iSan estimate of the number of entries in the table 
hcreate() May adjust this value upward to improve the performance of the resulting hash table TheGNU implementation 
of hsearch() will also enlarge the table if it gets nearly full. ma110c(3) is used to allocate space for the table 


The corresponding function hdestroy() frees the memory occupied by the hash table so that a new table can be constructed. 
item iS Of type entry, which is atypedef defined in <search.h> and includes these dements: 


typedef struct entry 
{ 

char *key ; 

char *data; 
} ENTRY; 


key points to the zero-terminated ASCII string that is the search key. data pointsto the data associated with that key. (A 
pointer to atype other than character should be cast to pointer-to-character.) hsearch() searches the hash table for an item 
with the same Key aSitem, and if successful returns a pointer to it. action determines what hsearch() does after an unsuccess- 
ful search. A value of enter instructs it to insert the new item, whereas a value of FIND means to return NULL. 
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RETURN VALUE 


hereate() returns NuLL if the hash table cannot be successfully installed. 


hsearch() returns NULL If action iSENTER and there isinsufficient memory to expand the hash table, or if action isFIND and 


item cannot befound in the hash table 


CONFORMS TO 
SVID, except that in SysV, the hash table cannot grow. 


BUGS 


The implementation can manage only one hash table at atime Individual hash table entries can be added, but not ddeted. 


EXAMPLE 


The following program inserts 24 items into a hash table and then prints some of then: 


#include <stdio.h> 
#include <search.h> 
char *data[]={ "alpha", "bravo", "charley", "delta", 
"echo", "foxtrot", "golf", "hotel", "india", "juliette", 
"kilo", "lima", "mike", "november", "oscar", "papa", 
"quebec", "romeo", "sierra", "tango", "uniform", 
"victor", "whiskey", "x-ray", "yankee", "zulu" 
}; 
int main() 
{ 
ENTRY e, *ep; 
inti; 
/* start with small table, and let it grow */ 
hcreate(3) ; 
for (i = 0; i < 24; i++) 
{ 
e.key = datali]; 
/* data is just an integer, instead of a pointer 
to something */ 
e.data = (char *)i; 
ep = hsearch(e, ENTER); 
/* there should be no failures */ 
if(ep == NULL) {fprintf(stderr, “entry failed\n"); exit(1);} 
} 
for (i = 22; i < 26; i ++) 
/* print two entries from the table, and show that 
two are not in the table */ 





{ 

e.key = datalil; 

ep = hsearch(e, FIND); 

printf ("%9.9s -> %9.9s:%d\n", e. key, ep?ep->key : "NULL" 
ep ?(int) (ep->data):0); 

} 

return Q; 


} 
SEE ALSO 


bsearch(3), lsearch(3), tsearch(3), malloc(3) 


GNU, 30 Septenber 1995 


iné@_aton, in_addr, inet_network, ine@_ntoa, inet_makeaddr, iné_Inaof, inet_netof 
hypot 


hypot— Euclidean distance function 


SYNOPSIS 


#include <math.h> 
double hypot(double x, double y); 


DESCRIPTION 


The hypot() function returns the sqrt(x*x+y*y). T hisis the length of the hypotenuse of a right-angle triangle with sides of 
length x and y, or the distance of the point (x, y) from the origin. 


CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 
sqrt(3) 
25 June1993 


index, rindex 


index, rindex— Locate character in string 


SYNOPSIS 


#include <string.h> 
char *index(const char *s ,int c); 
char *rindex(const char *s ,int c); 


DESCRIPTION 
The index() function returns a pointer to the first occurrence of the character « in the strings. 
The rindex() function returns a pointer to the last occurrence of the character in the strings. 
The terminating nuLt character is considered to be a part of the strings. 


RETURN VALUE 


The index() and rindex() functions return a pointer to the matched character, or NuLL if the character isnot found. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 


memchr(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 
GNU, 12 April 1993 


inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, 
inet_lnaof, inet_netof 


inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, inet_netof— Internet address- manipulation 
routines 


Part III: Library Functions 


SYNOPSIS 


#include <sys/socket.h> 

#include <netinet/in.h> 

#include <arpa/inet.h> 

int inet_aton(const char *cp, struct in_addr *inp); 
unsigned long int inet_addr(const char *cp); 
unsigned long int inet_network(const char *cp); 
char *inet_ntoa(struct in_addr in); 

struct in_addr inet_makeaddr(int net, int host); 
unsigned long int inet_lnaof(struct in_addr in); 
unsigned long int inet_netof(struct in_addr in); 


DESCRIPTION 


inet_aton() converts the Internet host address cp from the standard numbers-and-dots notation into binary data and stores it 
in the structure that inp points to. inet_aton returns nonzero if the address is valid, and a if it is not. 





The inet_addr() function converts the| nternet host address cp from numbers-and-dots notation into binary datain network 
byte orde. If the input isinvalid, -1 isreturned. This is an obsolete interface to inet_aton; it is obsolete because -1 isa valid 
address (255.255.255.255), and inet_aton provides acleaner way to indicate error return. 


The inet_network() function extracts the network number in network byte order from the address cp in numbers-and-dots 
notation. If the input is invalid, -1 is returned. 


The inet_ntoa() function converts the Internet host address given in network byte order to a string in standard numbers- 
and-dots notation. The string is returned in a statically allocated buffer, which subsequent calls will overwrite. 


The inet_makeaddr() function makes an Internet host address in network byte order by combining the network number net 
with the local addresshost in network net, both in local host byte order. 


The inet_inaof() function returns the local host address part of the Internet addressin. Thelocal host address is returned in 
local host byte order. 





The inet_netof() function returns the network number part of the|nternet addressi n. Thenetwork number is returned in 
local host byte order. 


Thestructure in_addr aS used in inet_ntoa(), inet_makeaddr(), inet_lnoaf(), aNd inet_netof() iS defined in netinet/in.h as 


struct in_addr { 
unsigned long int s_addr; 
} 


N ote that on the i80x86 the host byte order is Least Significant Byte first, whereas the network byte order, as used on the 
Internet, is M ost Significant Byte first. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 


gethostbyname(3), getnetent(3), hosts(5), networks(5) 
BSD, 3 Septenber 1995 


infnan 


infnan— D eals with infinite or not-a-number (N aN ) result 


SYNOPSIS 


#include <math.h> 
double infnan(int error); 


initgroups 
DESCRIPTION 


The infnan() function returns a suitable value for infinity and not-a-number (N aN ) results. The value of error Can be ERANGE 
to represent infinity, or anything else to represent N aN . errno isalso set. 


RETURN VALUE 
If error iSERANGE (Infinity), HUGE_vAL is returned. 
If error iS -ERANGE (-Infinity), -HuGE_VAL is returned. 
If error iSanything else, Nan is returned. 


ERRORS 
ERANGE The value of error is positive or negative infinity. 
EDOM The value of error isnot-a-number (N aN ). 
CONFORMS TO 
BSD 4.3 


GNU, 2 June1993 


initgroups 
initgroups— Initializes the supplementary group access list 


SYNOPSIS 


#include <grp.h> 
#include <sys/types.h> 
int initgroups(const char *user, gid _t group); 


DESCRIPTION 


The initgroups() function initializes the group access list by reading the group database /etc/group and using all groups of 
which user isamember. The additional group group isalso added to the list. 


RETURN VALUE 


The initgroups() function returns on success, or -1 if an error occurs. 


ERRORS 


EPERM The calling process does not have sufficient privileges. 
ENOMEM Insufficient memory to allocate group information structure. 


FILES 


/etc/group group database file 


CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 
getgroups(2), setgroups(2) 
GNU, 5 April 1993 
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inndcomm 


inndcomm—1N ND communication part of InterN etN ews library 


SYNOPSIS 


#include “inndcomm.h" 
int ICCopen() 

int ICCclose() 

void ICCsettimeout (i) 
int i; 

int ICCcommand(cmd, argv, replyp) 
char cmd; 

char *argv[]; 

char **replyp; 

int ICCcancel(mes gid) 
char *mesgid; 

int ICCreserve(why ) 
char *why; 

int ICCpause(why ) 

char *why; 

int ICCgo(why ) 

char *why ; 

extern char *I CCfailure; 


DESCRIPTION 


The routines described in this manual page are part of the InterN €tN ews library, 1ibinn(3). They are used to send com- 
mands to arunning inna(8) daemon on the local host. T heletters|CC stand for Innd Control Command. 


ICCopen creates a UN IX-domain datagram socket and bindsit to the server’s control socket. It returns -1 on failure or @ on 
success. T his routine must be called before any other routine. 


ICCclose Closes any descriptors that have been created by 1ccopen. It returns -1 on failure or @ on success. 


ICCsettimeout can be called before any of the following routines to determine how long thelibrary should wait before giving 
up on getting the server's reply. This is done by setting and catching a sIGALrM signal(2). If the timeout is less than 0, no 
reply will be waited for. The sc_SHUTDOWN, SC_XABORT, and sc_XEXEC Commands do not get a reply either. The default, which 
can be obtained by setting the timeout to 0, isto wait until the server replies. 


ICCcommand sends the command cmd with parameters argv to theserver. It returns -1 on error. If the server replies, and rep! yp 
isnot NULL, it will be filled in with an allocated buffer that contains the full text of the server's reply. T his buffer is a string in 
the form <di gits><space><text> wheredi gits isthe text value of the recommended exit code @ indicates success. Replies 
longer than 4,000 bytes will be truncated. T he possible values of cmd are defined in the inndcomm.h header file. The param- 
eters for each command are described in ctlinna(8). T his routine returns -1 on communication failure; on success it returns 
the exit status sent by the server, which will never be negative. 


ICCcancel sends a cancel message to the server. mesgid isthe message|ID of the article that should be canceled. The return 
value is the same as for 1cccommand. 


ICCpause, 1CCreserve, and 1cCgo send apause, reserve, or go command to the serve, respectively. If 1ccreserve iS used, the 
why Value used in the rccpause invocation must match; the value used in the 1ccgo invocation must always match the one 
used in the 1ccpause invocation. The return value for all three routines is the same as for 1cccommand. 


If any of these routines fail, the 1ccfailure variable will identify the system call that failed. 


HISTORY 


Written by Rich $alz (rsalze@uunet.uu.net) for InterN etN ews. 


SEE ALSO 


ctlinnd(8), innd(8), 1ibinn(3), 
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insque, remque 


insque, remque— Insert/Renovean item from a queue 


SYNOPSIS 


#include <stdlib.h> 
void insque(struct qelem * elem, struct qelem * prev); 
void remque(struct gel em*el em); 


DESCRIPTION 


insque() and remque() are functions for manipulating queues made from doubly linked lists. Each aement in thislist is of 
type struct qelem. 


The gelem structure is defined as 


struct gelem { 

struct gelem *q_forw; 
struct gelem *q_back; 
char q_data[1]; 

}; 


insque() inserts the element pointed to bye! em immediately after the element pointed to by prev, which must not be nuLL. 
remque() removes the element pointed to by e! em from the doubly linked list. 


CONFORMS TO 
SVR4 


BUGS 
The q_data field issometimes defined to be of type char *, and under Solaris 2.x, it doesn’t appear to exist at all. 


The location of the prototypes for these functions differs among several versions of UNIX. Some systems place then in 
<search.h>, Othersin <string.h>. Linux places then in <stdlib.h> because that seams to make the most sense. 


Some versions of UNIX (such asH P-U X 10.x) do not define a struct gelem but rather have the arguments to insque() and 
remque() be of type void *. 
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isalnum, 1salpha, isascii, isblank, iscntrl, isdigit, isgraph, 
islower, 1sprint, 1spunct, isspace, 1Supper, 1sxdigit 


isalnum, isalpha, isascii, isblank, iscntrl1, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit— 
Character classification routines 


SYNOPSIS 


#include <ctype.h> 
int isalnum (int 
int isalpha (int 
int isascii (int 
int isblank (int 
int iscntrl (int 
int isdigit (int 
int isgraph (int 
int islower (int 
int isprint (int 
int ispunct (int 
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int isspace (int c 
int isupper (int c 
int isxdigit (int 


DESCRIPTION 


T hese functions check whether c, which must have the value of an unsigned char or E0F, fallsinto a certain character class 
according to the current locale: 


isalnum 


isalpha 


isascii 


isblank 
iscntrl 
isdigit 
isgraph 
islower 
isprint 


ispunct 


isspace 





isupper 


isxdigit() 


RETURN VALUE 


Checks for an alphanumeric character; it is equivalent to (isalpha(c) !! isdigit(c)). 


Checks for an alphabetic character; in the standard C locale, it is equivalent to (isupper(c) |! 
islower(c)). In some locales, there may be additional characters for which isalpha() is true— 
letters that are neither uppercase nor lowercase. 


Checks whether c isa 7-bit unsigned char value that fits into the ASCII character set. This 
function isaBSD extension and isalso an SVID extension. 


Checks for a blank character; that is, a space or atab. This function isaGNU extension. 
Checks for a control character. 

Checks for a digit (0 through 9). 

Checks for any printable character except space 

Checks for a lowercase character. 

Checks for any printable character, including space. 

Checks for any printable character that is not a space or an alphanumeric character. 


Checks for whitespace characters. T hey are space, form-feed ('\f'), newline ('\n'), carriage 
return ('\r'), horizontal tab ('\t'), and vertical tab (‘\v'). 


Checks for an uppercase letter. 
Checks for a hexadecimal digit (that is, oneof01234567890abcdefABCD EF). 


The values returned are nonzero if the character c falls into the tested class, and 0 if it does not. 


CONFORMS TO 


ANSI C, BSD 4.3. isascii() isaBSD extension and is also an SVID extension. isblank() isaGNU extension. 


BUGS 


The details of what characters belong in which class depend on the current locale For example, isupper() will not recognize 
an A with an umlaut (A) as an uppercase letter in the default C locale 


SEE ALSO 


tolower(3), toupper(3), setlocale(3), ascii(7), locale(7) 


isatty 


GNU, 2 Septenbe 1995 


isatty— T ests whether this descriptor refers to a terminal 


SYNOPSIS 


#include <unistd.h> 
int isatty (int desc ); 


DESCRIPTION 


isatty returns 1 if desc isan open descriptor connected to aterminal, and o otherwise. 


j0,j2, jn, yO, y1, yn 


CONFORMS T0 
SVID, AT&T, X/OPEN, BSD 4.3 


SEE ALSO 


fstat(2), ttyname(3) 
Linux, 20 April 1995 


isinf, isnan, finite 
isinf, isnan, finite—T est for infinity or not-a-number (N aN ) 
SYNOPSIS 


#include <math.h> 

int isinf(double value); 
int isnan(double value); 
int finite(double value); 


DESCRIPTION 
The isint() function returns -1 if value represents negative infinity, 1 if value represents positiveinfinity, and @ otherwise 
The isnan() function returns a nonzero value if val ve isnot-a-number (N aN ), and @ otherwise. 
The finite() function returns anonzero value if val ve isfinite or isnot anot-a-number (N aN ) value, and a otherwise. 


CONFORMS TO 
BSD 4.3 
GNU, 2 June1993 


jQ, ji, jn, y0, y1,yn 


j0, j1, in, y®, y1, yn— Bessel functions 


SYNOPSIS 


#include <math.h> 
double jQ@(double x 


double j1(double x); 
double jn(int n, double x); 
double yQ@(double x); 
double y1(double x); 
double yn(int n, double x); 


DESCRIPTION 


The jo() and j1() functions return Bessel functions of x of the first kind of orders 0 and 1, respectively. The jn()function 
returns the Besse function of x of the first kind of order n. 


The yo) and y1() functions return Bessel functions of x of the second kind, orders 0 and 1, respectively. T he yn() function 
returns the Bessd function of x of the second kind, order n. 


For the functions yo(), yi() and yn(),the value of x must be positive For negative values of x, these functions return 
-HUGE_VAL. 


CONFORMS TO 
SVID 3, BSD 4.3 
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BUGS 
There are errors of up to 2e-16 in the values returned by jo(), j1(), and jn() for values of x between -8 and 8. 
26 June1993 


killpg 
killpg— Sends a signal to all members of a process group 


SYNOPSIS 


#include <signal.h> 
int killpg(pid_t pidgrp, int signal); 
DESCRIPTION 


The killpg() function causes the signal si gna! to besent to all the processes in the process group pi dgrp or to the processes’ 
own process group if pidgrp is equal to 0. 


It is equivalent to kill(-pidgrp, signal) ;. 


RETURN VALUE 
The value returned is -1 on error, or 0 for success. 
ERRORS 
Errors are returned in errno and can be one of the following: 
EINVAL Signal is invalid. 
ESRCH Process group does not exist. 
EPERM Theuser ID of the calling process isnot equal to that of the process the signal is sent to, and the user ID is 


not that of the super-user. 


SEE ALSO 
kill(2), signal(2), signal(7) 
GNU, 4 April 1993 


labs 


labs— Computes the absolute value of along integer 


SYNOPSIS 


#include <stdlib.h> 
long int labs(long int j ); 


DESCRIPTION 


The 1abs() function computes the absolute value of the long integer argument | . 


RETURN VALUE 


Returns the absolute value of the long integer argument. 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


Idiv 


NOTES 
Trying to take the absolute value of the most negative integer is not defined. 


SEE ALSO 


abs(3), ceil(3), floor(3), fabs(3), rint(3) 
GNU, 6 June1993 


ldexp 


1dexp— M ultiplies floating-point number by integral power of 2 


SYNOPSIS 


#include <math.h> 
double ldexp(double x, int exp); 


DESCRIPTION 


The 1dexp() function returns the result of multiplying the floating-point number x by 2 raised to the power exp. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
frexp(3), modf(3) 
BSD, 6 June1993 


ldiv 
1div— Computes the quotient and remainder of long integer division 


SYNOPSIS 


#include <stdlib.h> 
ldiv_t ldiv(long int numer, long int denom); 


DESCRIPTION 


The idiv() function computes the value numer /denom and returns the quotient and remainder in astructure named idiv_t 
that contains two long integer members named quot and rem. 


RETURN VALUE 


The idiv_t structure 


CONFORMS T0 
SVID 3, BSD 4.3, ISO 9899 


SEE ALSO 
div(3) 
GNU, 29 March 1993 
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Igamma 


1gamma— Logs gamma function 


SYNOPSIS 


#include <math.h> 
double lgamma(double x); 


DESCRIPTION 


The igamma() function returns the log of the absolute value of the Gamma function. The sign of the Gamma function is 


returned in the external integer si gngam. 
For negative integer values of x, 1gamma() returns HUGE_VAL, and errno is Set to ERANGE. 


ERRORS 


ERANGE Invalid argument— negative integer value of x. 


CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 


infnan(3) 


libinn 
libinn— InterN eN ews library routines 


SYNOPSIS 


#include "libinn.h" 
typedef struct _TIMEINFO { 
time_t time; 
long usec; 
long tzone; 
} TIMEINFO; 


char *GenerateMessageID() 


void HeaderCleanFrom(f rom) 
char *from; 


char *HeaderFind(Article, Header, size) 


char *Article; 
char *Header ; 
int size; 


FILE *CAopen(FromServer, ToServer ) 
FILE *FromServer ; 
FILE *ToServer ; 


FILE *CAlistopen(FromServer, ToServer, 


FILE *FromServer ; 
FILE *ToServer ; 
char *request ; 


BSD, 25 June1993 


void CAclose() 


struct _DDHANDLE *DDstart(FromServer, ToServer ) 
FILE *FromServer ; 

FILE *ToServer ; 

} DDHANDLE; 


void DDcheck(h, group) 
DDHANDLE *h; 
char *group; 


char * DDend(h) 
DDHANDLE *h; 


void CloseOnExec(fd, flag) 
int ; 
int flag; 


int SetNonBlocking(fd, flag) 
int ; 
int flag; 


int LockFile(fd, flag) 
int 7 
int flag; 














char * GetConfigValue(val ue) 
char *value; 


char * GetFileConfigValue (val ue) 
char *value; 


char * GetFQDN() 





char * GetModeratorAddress (group ) 
char *group; 


int GetResourceUsage(usertime, systime) 
double *usertime; 
double *systime; 


int GetTimeInfo(now) 
TIMEINFO *now; 


int NNTPlocalopen(FromServerp, ToServerp, errbuff ) 
FILE **FromServerp; 

FILE **ToServerp; 

char *errbuff ; 


int NNTPremoteopen(FromServerp, ToServerp, errbuff ) 
FILE **FromServerp; 

FILE **ToServerp; 

char *errbuff ; 


int NNTPconnect(host, FromServerp, ToServerp, errbuff ) 
char *host ; 

FILE **FromServerp; 

FILE **ToServerp; 

char *errbuff ; 


int NNTPcheckarticle(text ) 
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char *text; 


int NNTPsendarticle(text, ToServer, Terminate) 
char *text; 

FILE *ToServer ; 

int Terminate; 


int NNTPsendpassword(server, FromServer, ToServer ) 
char *server ; 

FILE *FromServer ; 

FILE *ToServer ; 


void Radix32(value, p) 
unsigned long value; 
char *p; 


char * ReadInFile(name, Sbp) 
char *name; 
struct stat *Sbp; 


char * ReadInDescriptor(fd, Sbp) 
int fd; 
struct stat *Sbp; 


char * INNVersion() 


DESCRIPTION 


libinn is a library of utility routines for manipulating U senet articles and related data. It is not necessary to use the header file 
libinn.h; if it is not available, it is only necessary to properly declare the T1meInFo datatype as shown in the preceding code 


GenerateMessageID uses the current time process!D, and fully qualified domain name of the local host to create a M essage 
ID header that is highly likely to be unique T hereturned value points to static space that is reused on subsequent calls. 


HeaderCleanFrom removes the extraneous information from the value of a From or Reply-To header and leaves just the official 
mailing address. In particular, the following transformations are made to thef rom parameter: 
address -> address 


address (stuff) -> address 
stuff <address>-> address 


The transformations are simple and are based on RFC 1036, which limits the format of the header. 


HeaderFind Searches through articie looking for the specified Header. size Should bethelength of the header name It 
returns a pointer to the value of the header, skipping leading whitespace, or nuLt if the header cannot be found. article 
should bea standard C string containing the text of the article the end of a header isindicated by ablank line: two 
consecutive \n characters. 


CAopen and CAclose provide news clients with access to the active file; theca stands for Client Active. cAopen opens the 
active(5) file for reading. It returns a pointer to an open FILE, or NULL On error. If a local or an N FS-mounted copy exists, 
CAopen will use that file The FromServer and toServer parameters should be F1Les connected to the NNTP server for input 
and output, respectively. (See the discussions of NNTPremoteopen and NNTPlocalopen later in this section.) If either parameter is 
NULL, CAopen will just return NuLL if the fileis not locally available. If neither is NULL, CAopen will usethem to query theN NTP 
server using the “list” command to make a local temporary copy. 


The cAlistopen sends a “list” command to the server and returns a tanporary file containing the results. Ther equest 
parameter, if not NULL, will be sent as an argument to the command. Unlike cAopen, this routine will never use a locally 
available copy of the active file. 


CAclose Closes the active file and renoves any temporary file that might have been created by cAopen OF CAlistopen. 


libinn 


CloseOnExec can make a descriptor close-on- exec so that it isnot shared with any child processes. If the flag isnonzero, thefile 
isso marked; if it is@, the closeon-exec mode is cleared. 


DDstart, DDcheck, and DDend are used to set the Distribution header; the pp stands for D efault Distribution. T he 
distrib.pats(5) file is consulted to determine the proper value for the Distribution header after all newsgroups have been 
checked. pdstart begins the parsing. It returns a pointer to an opaque handle that should be used on subsequent calls. T he 
FromServer andToServer parameters should be FILES connected to the NNTP server for input and output, respectively. If 
either parameter iS NULL, an empty default will ultimately be returned if the file is not locally available. 


DDcheck should be called with the handle, h, returned by ppdstart and anew group, group, to check. It can be called as often as 
necessary. 


DDend releases any state maintained in the handle and returns an allocated copy of the text that should be used for the 
Distribution header, 


SetNonBlocking gables (if f1ag ismonzero) or disables (if f! ag is @) non-blocking 1/O on the indicated descriptor. It returns 
-1 on failure and @ on success. 


LockFile tries to lock the file descriptor fd. If f!ag isnonzero it will block until the lock can be made otherwiseit will return 
-1 if the file cannot be locked. It returns -1 on failure and @ on success. 


GetConfigValue returns the value of the specified configuration parameter. (See inn.conf(5) for details on the parameters and 
their interpretation.) The returned value points to static space that is reused on subsequent calls. 


GetFileConfigValue returns the specified configuration parameter from the inn.con¢ file without checking for any defaults. 
The returned value points to static space that is reused on subsequent calls, or NuLL if the value is not present. 


GetFaon returns the fully qualified domain name of the local host. The returned value points to static space that is reused on 
subsequent calls, or NULL on error. 


GetModeratorAddress returns the mailing address of the moderator for the specified group Or NULL ON error. (See moderators(5) 
for details on how the address is determined.) GetModeratorAddress does no checking to see if the specified group is actually 
moderated. T he returned value points to static space that is reused on subsequent calls. 


GetResourceUsage fillsin theusertime and systime parameters with the total user and systen time used by the current process 
and any children it may have spawned. It gets the values by doing a times(2) system call. It returns -1 on failure, or 9 on 
SUCCESS. 


GetTimeInfo fills in thenow parameter with information about the current time andtzone. Thetime andusec fields will be 
filled in by acall to gettimeofday(2). T heti me field will be filled in by acall to time(2), and the usec fidd will beset to 0. The 
tzone field will be filled in with the current offset from GMT. Thisis done by calling 1oca1time(3) and taking the value of 
thet m gmtoff fidd, negating it, and dividing it by 60. Thisis done by calling 1ocaltime(3) and comparing the value with that 
returned by a call to gmtime(3). For efficiency, thet zone fidd is only recalculated if more than an hour has passed since the 
last time GetTimeInfo was Called. T his routine returns -1 on failure, and @ on success. 


NNTPlocalopen opens aconnection to the private port of an InterN etN ews server running on the local host. It returns -1 on 
failure, or @ ON SUCCESS. FromServerp aNd ToServerp Will be filled in with FILes that can be used to communicate with the 
server. err buff Can athe benuLt or a pointer to a buffer at least 512 bytes long. If it isnot nuLL, and the server refuses the 
connection, it will be filled in with the text of the server's reply. This routine is not for general use; it is a subroutine for 
compatibility with systems that have UN 1X-domain stream sockets. It always returns -1. 


NNTPremoteopen does the same as NNTPlocalopen, except that it calls GetConfigValue to find the name of the local server and 
opens aconnection to the standard NNTP port. Any client program can use this routine It returns -1 on failure, or 9 on 
SUCCESS. 


NNTPconnect iS the same aS NNTPremoteopen, except that the desired host is given asthehost parameter. 


NNTPcheckarticle verifies that the text meets the NNTP limitations on line length. It returns -1 on failure, or o if the text is 
valid. 
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NNTPsendarticle writes text on ToServer using NNTP conventions for line termination. T he text should consist of oneor 


more lines ending with a newline If Terminate isnonzero, the routine will a 
the stream. It returns -1 on failure, or @ on success. 


NNTPsendpassword sends authentication information to an NNTP server by fi 
passwd.nntp(5) file server contains the name of the host; GetConfigValue wi 


so write the NNTP data-termination marker on 


nding the appropriate entry in the 
| be used if server iSNULL. FromServer and 


ToServer Should be FILes that are connected to theserver. N o action is taken if the specified host is not listed in the password 


file. 





Radix32 converts the number in val ue into aradix-32 string in the buffer poi 


nted to by p. Thenumber is split into five bit 


pieces, and each piece is converted into a character using the alphabet 0... 9a... v to represent the numbers 0-32. Only the 
lowest 32 bits of val ue are used, SO p need only point to a buffer of eight bytes (seven characters and the trailing \@). 


ReadInFile reads the file named name into allocated memory, appending a terminating \o byte. It returns a pointer to the 


space, Or NULL On error. If Sbp isnot NULL, it istaken as the address of a place 


to store the results of a stat(2) call. 


ReadInDescriptor performs the same function aS ReadInFile, except that fa refers to an already-open file. 


INNVersion returns a pointer to astring identifying the NN version, suitable for printing in logon banners. 


EXAMPLES 


char *p; 

char *Article; 

char buff[256] ; 

FILE *F; 

FILE *ToServer ; 

FILE *FromServer ; 

if ((p = HeaderFind(Article, "From", 4)) == NULL) 
Fatal("Can't find From line"); 

(void)strepy(buff, p); 

HeaderCleanFrom(buff ); 

if ((F = CAopen(FromServer, ToServer)) == NULL) 
Fatal("Can't open active file"); 

/* Don't pass the file on to our children. */ 

CloseOnExec(fileno(F), 1); 

/* Make a local copy. */ 

p = ReadInDescriptor(fileno(F), (struct stat *)NULL); 

/* Close the file. */ 

CAclose(); 

if (NNTPremoteopen(&FromServer, &ToServer) < Q) 
Fatal("Can't connect to server"); 

if ((p = GetModeratorAddress("comp.sources.unix")) == NULL) 

Fatal("Can't find moderator's address"); 


HISTORY 


Written by Rich $alz (rsalze@uunet.uu.net) for InterN etN ews. 


SEE ALSO 


active(5), dbz(3z), parsedate(3), inn.conf(5), inndcomm(3), moderators(5), passwd. nntp(5) 
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1ibpbm— Functions to support portable bitmap programs 


GNU, 30 October 1996 


libpbm 


SYNOPSIS 


#include <pbm.h> 
cc ... libpbm.a 


DESCRIPTION —PACKAGEWIDE ROUTINES 


The following sections describe string and file managenent routines available in 1ibpbm. 


KEYWORD MATCHING 
The following does a case-insensitive match of str against keyword: 


int pm_keymatch( char* str, char* keyword, int minchars ) 
str Can bea leading substring of keyword, but at least mi nchars must be present. 
LOG BASE TWO 
This converts between amaxval and the minimum number of bits required to hold it: 


int pm_maxvaltobits(int maxval ) 
int pm_bitstomaxval(int bits) 


MESSAGES AND ERRORS 
This is a printt()-style routine to write an informational message: 


void pm_message(char* fmt, ... ) 


This is a printf() style routine to write an error message and abort: 


void pm_error(char* fmt, ... ) 


The following writes a usage message; the string should indicate what arguments are to be provided to the program: 


void pm_usage(char* usage) 


GENERIC FILE MANAGEMENT 
The following opens the given file for reading, with appropriate error checking: 
FILE* pm_openr(char* name) 
A filename of - istaken as equivalent to stdin. 
The following opens the given file for writing, with appropriate error checking: 
FILE* pm_openw(char* name) 
The following closes the file descriptor, with appropriate error checking: 
void pm_close(FILE* fp) 


ENDIAN 1/0 
The following are routines to read and write short and long intsin either big- or little endian byte order: 


int pm_readbigshort(FILE* in, short* sP) 
int pm_writebigshort(FILE* out, short s) 
int pm_readbiglong(FILE* in, long* |P) 

int pm_writebiglong(FILE* out, long | ) 

int pm_readlittleshort(FILE* in, short* sP) 
int pm_writelittleshort(FILE* out , short s) 
int pm_readlittlelong(FILE* in, long* | P) 
int pm_writelittlelong(FILE* out , long | ) 


DESCRIPTION —PBM-SPECIFIC ROUTINES 


The following sections describe file management routines available in 1ibpbm. 


967 


968 Part III: Library Functions 


TYPES AND CONSTANTS 
Each bit should contain only the values of PBM_WHITE Or PBM_BLACK: 


typedef ... bit; 
#define PBM_WHITE ... 
#define PBM_BLACK ... 


T hese are routines for distinguishing different file formats and types: 


#define PBM_FORMAT ... 

#define RPBM_FORMAT ... 
#define PBM_TYPE PBM_FORMAT 
#define PBM_FORMAT TYPE(f) ... 


INITIALIZATION 
All PBM programs must call this routine 


void pbm_init(int* argcP, char* argv[] ) 


MEMORY MANAGEMENT 
This allocates an array of bits: 


bit** pbm_allocarray(int cols, int rows) 
This allocates a row of the given number of bits: 


bit* pbm_allocrow(int cols) 


This frees the array allocated with pbm_allocarray() containing the given number of rows: 


void pbm_freearray(bit** bits, int rows) 





This frees a row of bits: 


void pbm_freerow(bit* bitrow) 


READING FILES 
This reads the header from a PBM file filling in therows, cols, and format variables: 
void pbm_readpbminit(FILE* fp, int* colsP, int* rowsP, int* formatP) 
This reads a row of bitsinto thebitrow array (format andcols arefilled in by pbm_readpbminit()): 
void pbm_readpbmrow(FILE* fp, bit* bitrow, int cols, int format ) 
This function combines pbm_readpbminit(), pbm_allocarray(), aNd pbm_readpbmrow(): 
bit** pbm_readpbm(FILE* fp, int* colsP, int* rowsP) 
It reads an entire bitmap file into memory, returning the allocated array and fillingin therows and cols variables. 
This reads an entire file or input stream of unknown sizeto a buffer and allocates more memory as needed: 
char* pm_read unknown size(FILE* fp, long* nread) 


The calling routine has to free the allocated buffer with free(). pm_read_unknown_size() returns a pointer to the allocated 
buffer; the nread argument returns the number of bytes read. 


WRITING FILES 
This writes the header for a portable bitmap file: 
void pbm_writepbminit(FILE* fp, int cols, int rows, int forceplain) 
Theforceplain flag forces a plain-format file to be written, as opposed to a raw-format one 
This writes a row from a portable bitmap: 


void pbm_writepbmrow(FILE* fp, bit* bitrow, int cols, int forceplain) 
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This writes the header and all data for a portable bitmap: 


void pbm_writepbm(FILE* fp, bit** bits, int cols, int rows, int forceplain) 
This function combines pbm_writepbminit() and pbm_writepbmrow(). 


SEE ALSO 


Libpgm(3), 1ibppm(3), 1ibpnm(3) 


AUTHOR 
Copyright © 1989, 1991 by T ony H ansen and J ef Poskanzer 


libpgm 
1ibpgm— Functions to support portable graymap programs 


SYNOPSIS 


#include <pgm.h> 
cc... libpgm.a libpbm.a 


DESCRIPTION 
The following sections describe memory and file management routines available in 1ibpgm. 


TYPES AND CONSTANTS 
Each gray should contain only the values between 0 and PGM_MAXMAXVAL. 


pgm_pbmmaxval iSthe maxval used when aPGM program reads aPBM file Normally it is 1, but for some programs, a larger 


value gives better results. 


typedef ... gray; 
#define PGM_MAXMAXVAL ... 
extern gray pgm_pbmmaxval; 


The following are for distinguishing different file formats and types: 


#define PGM_FORMAT ... 

#define RPGM_FORMAT ... 

#define PGM_TYPE PGM FORMAT 
int PGM_FORMAT_TYPE(int format ) 


INITIALIZATION 
All PGM programs must call this routine 


void pgm_init(int* argcP, char* argv[] ) 


MEMORY MANAGEMENT 
This allocates an array of grays: 


gray** pgm_allocarray(int cols, int rows) 
This allocates a row of the given number of grays: 
gray* pgm_allocrow(int cols) 


This frees the array allocated with pgm_allocarray() containing the given number of rows: 


void pgm_freearray(gray** grays, int rows) 





This frees a row of grays: 


void pgm_freerow(gray* grayrow) 
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READING FILES 


This reads the header from aPGM file, filling in ther ows, cols, maxval , and format variables: 


void pgm_readpgminit(FILE* fp, int* colsP, int* rowsP, gray* maxvalP, 
int* formatP) 


This reads a row of grays into the grayrow array. format, cols, aNd maxval arefilled in by pgm_readpgminit(): 
void pgm_readpgmrow(FILE* fp, gray* grayrow, int cols, gray maxval, int format) 
This function combines pgm_readpgminit(), pgm_allocarray(), aNd pgm_readpgmrow(): 


gray** pgm_readpgm(FILE* fp, int* colsP, int* rowsP, gray* maxval P) 


It reads an entire graymap file into memory, returning the allocated array and filling in therows, cols, and maxval variables. 


WRITING FILES 


This writes the header for a portable graymap file 


void pgm _writepgminit( FILE* fp, int cols, int rows, gray maxval, 
int forceplain ) 


Theforceplain flag forces a plain-format file to be written, as opposed to a raw-format one 


This writes a row from a portable graymap: 


void pgm _writepgmrow(FILE* fp, gray* grayrow, int cols, gray maxval, 
int forceplain) 


This function combines pgm_writepgminit() and pgm_writepgmrow(); it writes the header and all data for a portable graymap: 


void pgm_writepgm( FILE* fp, gray** grays, int cols, int rows, gray maxval , int forceplain) 
pgm_| Pg Ps 9 


SEE ALSO 


Libpbm(3), 1ibppm(3), 1ibpnm(3) 


AUTHOR 


Copyright ° 1989, 1991 by T ony Hansen and J e& Poskanzer. 
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libpnm— Functions to support portable anymap programs 


SYNOPSIS 


#include <pnm.h> 
cc... libpnm.a libppm.a libpgm.a libpbm.a 


DESCRIPTION 


The following sections describe memory and file management routines available in 1ibpnm. 


TYPES AND CONSTANTS 


Each xe1 contains three xelvais, each of which should contain only a value between @ and PNM_MAXMAXVAL. pnm_pbmmaxval iS 
the maxval used when aPN M program reads aPBM file. Normally it is 1, but for some programs, a larger value gives better 
results. 


typedef ... xel; 

typedef ... xelval; 

#define PNM_MAXMAXVAL ... 
extern xelval pnm_pbmmaxval; 
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XEL MANIPULATIONS 
This macro extracts a single value from an xe1 when you know it’s from aPBM or PGM file 
xelval PNM_GET1( xel x ) 
When the xe1 isfrom aPPM file use PPM_GETR(), PPM_GETG(), aNd PPM GETB(). 
This macro assigns a single value to an xe1 when you know it’s from a PBM or PGM file: 
void PNM_ASSIGN1( xel x, xelval v ) 
When the xe1 isfrom aPPM file use PPM_ASSIGN(). 
This macro checks two xe1s for equality: 
int PNM_EQUAL( xel x, xel y ) 


This oneisfor distinguishing different file types: 
int PNM_FORMAT TYPE( int format ) 


INITIALIZATION 
All PNM programs must call this routine: 


void pnm_init( int* argcP, char* argv[] ) 


MEMORY MANAGEMENT 
This allocates an array of xe1s: 
xel** pnm_allocarray( int cols, int rows ) 
This allocates a row of the given number of xe1s: 
xel* pnm_allocrow( int cols ) 
This frees the array allocated with pnm_allocarray() that contains the given number of rows: 


void pnm_freearray( xel** xels, int rows ) 





This frees a row of xeis: 


void pnm_freerow( xel* xelrow ) 


READING FILES 
This reads the header from a PNM file filling in the rows, cols, maxval, and format variables: 


void pnm_readpnminit( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 


This reads a row of xdsinto the xelrow array. format, cols, and maxval are filled in by pnm_readpnminit(): 
void pnm_readpnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format ) 


This reads an entire anymap file into memory, returning the allocated array and filling in the rows, cols, maxval, and format 
variables: 


xel** pnm_readpnm( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 


This function combines pnm_readpnminit(), pnm_allocarray(), and pnm_readpnmrow(). Unlike the equivalent functions in 
PBM, PGM, and PPM, it returns the format so you can tell what type the file is. 


WRITING FILES 
This writes the header for a portable anymap file: 


void pnm_writepnminit( FILE* fp, int cols, int rows, xelval maxval, int format, 
int force-plain) 
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Unlike the equivalent functions in PBM, PGM, and PPM, you have to specify the output type. T he forceplain flag forces a 
plain-format file to be written, as opposed to a raw-format one 
This writes a row from a portable anymap: 
void pnm_writepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, 
int forceplain ) 
This writes the header and all data for a portable anymap: 
void pnm_writepnm( FILE* fp, xel** xels, int cols, int rows, xelval maxval, int format, 
int forceplain ) 
This function combines pnm_writepnminit() and pnm_writepnmrow(). 

FORMAT PROMOTION 
This promotes a row of xds from one maxval and format to a new set: 
void pnm_promoteformatrow( xel* xelrow, int cols, xelval maxval, int format, xelval new-maxval, 
int newformat ) 
Use this when combining multiple anymaps of different types— just take the maximum value of the maxvais and the max of 
the formats, and promote then all to that. 
This promotes an entire anymap: 
void pnm_promoteformat( xel** xels, int cols, int rows, xelval maxval, 
int format, xelval newmaxval, int newformat ) 

XEL MANIPULATION 
These return awhite or black xe1, respectivey, for the given maxval and format: 
xel pnm_whitexel( xelval maxval, int format ) 
xel pnm_blackxel( xelval maxval, int format ) 
This inverts an xe1: 
void pnm_invertxel( xel* x, xelval maxval, int format ) 
This figures out an appropriate background xe1 based on this row: 
xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format ) 
This figures out a background xe1 based on an entire anymap: 
xel pnm_backgroundxel( xel** xels, int cols, int rows, xelval maxval, 
int format ) 
This can do aslightly better job than pnm_backgroundxelrow(). 

SEE ALSO 
pbm(3), pgm(3), ppm(3) 

AUTHOR 


Copyright ° 1989, 1991 by T ony Hansen and J & Poskanzer. 
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libppm 


1ibppm— Functions to support portable pixmap programs 


SYNOPSIS 


#include <ppm.h> 
cc ... libppm.a libpgm.a libpbm.a 


TYPES AND CONSTANTS 


typedef ... pixel; 

typedef ... pixval; 

#define PPM_MAXMAXVAL ... 
extern pixval ppm_pbmmaxval; 


Each pixd contains three pixvais, each of which should contain only the values between @ and PPM_MAXMAXVAL. ppm_pbmmaxval 
is the maxval used when a PPM program reads a pew file N ormally it is 1; however, for some programs, a larger value gives 
better results. 


For distinguishing different file formats and types, use 


#define PPM_FORMAT ... 

#define RPPM_FORMAT ... 

#define PPM_TYPE PPM_FORMAT 

int PPM_FORMAT_TYPE( int format ) 


T hese three macros retrieve the red, green, or blue value from the given pixd: 


pixval PPM_GETR( pixel p ) 
pixval PPM_GETG( pixel p ) 
pixval PPM_GETB( pixel p ) 


This macro assigns the given red, green, and blue values to the pixd: 
void PPM_ASSIGN( pixel p, pixval red, pixval grn, pixval blu ) 
This macro checks two pixds for equality: 

int PPM_EQUAL( pixel p, pixel q ) 


The following macro scales the colors of pixel p according the old and new maximum values and assigns the new values to 
newp. It is intended to make writing ppm to whatever easier. 


void PPM_DEPTH( pixel newp, pixel p, pixval oldmaxval, pixval newmaxval ) 


This macro determines the luminance of the pixd p: 
float PPM_LUMIN( pixel p ) 


MEMORY MANAGEMENT 
Allocate an array of pixds: 
pixel** ppm_allocarray( int cols, int rows ) 
Allocate a row of the given number of pixels: 
pixel* ppm_allocrow( int cols ) 
Free the array allocated with ppm_allocarray() containing the given number of rows: 


void ppm_freearray( pixel** pixels, int rows ) 


Free a row of pixels: 


void pbm_freerow( pixel* pixelrow ) 
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READING PBM FILES 


void ppm_readppminit( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP, int* formatP ) 

Read the header from a pen file, filling in the rows, cols, maxval, and format variables. 

void ppm_readppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxval, int format ) 

Read a row of pixds into the pixelrow array. Format, cols, and maxval were filled in by ppm readppminit(). 
pixel** ppm_readppm( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP ) 


Read an entire pixmap file into memory, returning the allocated array and filling in the rows, cols, and maxval variables. T his 
function combines ppm_readppminit(), ppm_allocarray(), aNd ppm_readppmrow(). 


WRITING FILES 


void ppm_writeppminit( FILE* fp, int cols, int rows, pixval maxval, int forceplain ) 


W rite the header for a portable pixmanp file. The forceplain flag forces a plain-format file to be written, as opposed to a raw- 
format one 


void ppm_writeppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxval, int forceplain) 
W rite a row from a portable pixmap. 


void ppm_writeppm( FILE* fp, pixel** pixels, int cols, int rows, pixval maxval, int force-plain) 


W rite the header and all data for a portable pixmap. This function combines ppm_writeppminit() and ppm_writeppmrow(). 


COLOR NAMES 


This line parses an ASCII color name into a pixel: 
pixel ppm_parsecolor( char* colorname, pixval maxval ) 
The color can be specified in three ways: as aname, assuming that a pointer to an X11-style color names file was compiled 


in; as an X11-style hexadecimal number (#rgb, #rrggbb, #rrrgggbbb, Or #rrrrggggbbbb); or as a triplet of decimal floating 
point numbers separated by commas (r.r,g.g,b.b). 


This line returns a pointer to a string describing the given color: 


char* ppm_colorname( pixel* colorP, pixval maxval, int hexok ) 


If the X11 color names file is available and the color appears in it, that name is returned. O therwise, if thehexok flag is true, 
then a hexadecimal colorspec is returned; if hexok is false and the X11 color names file is available, then the closest matching 
color is returned; otherwise it’s an error. 


SEE ALSO 


pbm(3), pgm(3) 


AUTHOR 


Copyright © 1989, 1991 by T ony H ansen and J ef Poskanzer 


localeconv 


localeconv— Gets numaric formatting information 


SYNOPSIS 


#include <locale.h> 
struct lconv *localeconf (void); 
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DESCRIPTION 


The localeconf() function returns a string to astruct 1conv for the current locale. 
CONFORMS TO 
This command conformsto AN SI C and POSIX.1. 
Linux supports the portable locales C and PO SIX and also the European Latin-1 1SO -8859-1, and Russian KO 1-8 locales. 
The printt() family of functions may or may not honor the current locale 


SEE ALSO 


locale(1), localedet(1), strcol1(3), isalpha(3), setlocale(3), strftime(3), locale(7) 
GNU, 25 April 1993 


longjmp 
longjmp— N onlocal jump to a saved stack context 


SYNOPSIS 


#include <setjmp.h> 
void longjmp(jmp_buf env ,int val ); 


DESCRIPTION 


longjmp() and setjmp(3) are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. 
longjmp() restores the environment saved by the last call of setjmp() with the corresponding env argument. After 1ongjmp() is 
completed, program execution continues as if the corresponding call of setjmp() had just returned the value val. longjmp() 
cannot cause @ to be returned. If 1ongjmp isinvoked with a second argument of @, 1 will be returned instead. 


RETURN VALUE 


This function never returns, 


CONFORMS TO 
POSIX 


NOTES 


POSIX does not specify if the signal context will be restored or not. If you want to save restore signal masks, use 
siglongjmp(3). 1ongjmp() Makes programs hard to understand and maintain. If possible, an alternative should be used. 


SEE ALSO 
setjmp(3), sigsetjmp(2), siglongjmp(2) 
25 November 1994 


lfind, lsearch 


find, lsearch— Linear search of an array 


SYNOPSIS 


#include <stdlib.h> 
void *lfind(const void *key, const void *base, size t *nmemb, 
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size_t size,int(*compar )(const void *, const void *)); 
void *lsearch(const void *key, const void *base, size_t *nmemb, 
size_t size,int(*compar )(const void *, const void *)); 


DESCRIPTION 


lfind() and 1search() perform a linear search for key in thearray base, which has *nmemb dements of size bytes each. The 
comparison function referenced by compar is expected to have two arguments that point to the key object and to an array 
membe,, in that order, and which returns zero if the key object matches the array menber, and non-zero otherwise 


If 1search() does not find a matching element, then the key object isinserted at the end of thetable and *nmemb is 
incremented. 


RETURN VALUE 


1find() returns a pointer to amatching member of the array, or NuLL if no match is found. 1search() returns a pointer to a 
matching member of the array, or to the newly added member if no match is found. 


CONFORMS T0 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 


bsearch(3), hsearch(3), tsearch(3) 
GNU, 17 Septenber 1995 


calloc, malloc, free, realloc 


calloc, malloc, free, realloc— Allocate and free dynamic memory 


SYNOPSIS 


#include <stdlib.h> 

void *calloc(size_t nmemb, size_t size); 
void *malloc(size_t size); 

void free(void *ptr); 

void *realloc(void *ptr, size_t size); 


DESCRIPTION 


calloc() allocates memory for an array of nmemb elements of size bytes each and returns a pointer to the allocated manory. 
Thememory is set to zero. 


malloc() allocates size bytes and returns a pointer to the allocated memory. The memory is not cleared. 


free() frees thememory space pointed to by ptr, which must have been returned by a previous call to malloc(), calloc() or 
realloc(). If ptr iSNULL, NO Operation is performed. 

realloc() changes the size of the memory block pointed to by ptr to size bytes. The contents will be unchanged to the 
minimum of the old and new sizes; newly allocated memory will be uninitialized. If ptr is nuLL, the call is equivalent to 
malloc(size); if size iS equal to zero, the call is equivalent to free(ptr). Unless ptr iS NULL, it must have been returned by an 
earlier call to malloc(), calloc(), OF realloc(). 


RETURN VALUES 


For calloc() and malloc(), the value returned is a pointer to the allocated memory, which is suitably aligned for any kind of 
variable, or NuLL if the request fails. 





free() returns no value. 
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realloc()returns a pointer to the newly allocated memory, which is suitably aligned for any kind of variable and may be 
different from ptr, or NULL if the request fails or if size was equal to o. If realloc() fails, the original block is left untouched; 
it isnot freed or moved. 


CONFORMS TO 
ANSIC 


SEE ALSO 
prk(2) 
GNU, 4 April 1993 


molen 


mblen— D eermines the number of bytes in a character 


SYNOPSIS 


#include <stdlib.h> 
int_mblen(const char *s, size_t n); 


DESCRIPTION 


Thembien() function scansthefirst n bytes of thestrings and returns the number of bytes in a character. The mb1en() 
function is equivalent to 


mbtowc((wchat t*)Q@,s,n); 
except that the shift state of the mbtowc() function is not affected. 
RETURN VALUE 


The mblen()returns the number of bytes in a character, or -1 if the character is invalid, or o if it isaNuLL string. 


CONFORMS T0 
SVID 3,150 9899 


SEE ALSO 


mbstowcs(3), mbtowc(3), westombs(3), wetomb(3) 
GNU, 29 March 1993 


mostowcs 


mbstowcs— Converts a multibyte string to a wide character string 


SYNOPSIS 


#include <stdlib.h> 
size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n); 


DESCRIPTION 


The mbstowcs() function converts a sequence of multibyte characters from the arrays into a sequence of wide characters and 
stores up to n wide characters in the array pwcs. 
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RETURN VALUE 


mbstowcs() returns the number of wide characters stored, or -1 if s contains an invalid multibyte character. 


CONFORMS T0 
SVID 3,150 9899 


SEE ALSO 


mblen(3), mbtowc(3), westombs(3), wetomb(3) 
GNU, 29 March 1993 


motowc 


mbtowc— C onverts a multibyte character to a wide character 


SYNOPSIS 


#include <stdlib.h> 
int mbtowc(wchar_t *pwc, const char *s, size_t n); 


DESCRIPTION 


The mbtowe() function converts a multibyte character s, which isno longer than n bytes, into awide character and, if pwe is 
not NULL, stores the wide character in pwc. 


RETURN VALUE 


mbtowc() returnsthenumber of bytes in the multibyte character, or -1 if the multibyte character is not valid. 


CONFORMS T0 
SVID 3,150 9899 


SEE ALSO 


mblen(3), mbstowcs(3), westombs(3), wetomb(3) 
GNU, 29 March 1993 


memccpy 


memccpy— Copies memory area 


SYNOPSIS 


#include <string.h> 
void *memccpy(void *dest, const void *src,int c, size t n); 


DESCRIPTION 
Thememccpy() function copies no more than n bytes from memory areasrc to memory area dest , topping when the 
character c isfound. 

RETURN VALUE 


The memccpy() function returns a pointer to thenext character in dest after c, or NULL if c was not found in the first n 
characters of src. 
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CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 


beopy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3) 
GNU, 10 April 1993 


memchr 


memchr— Scans memory for a character 


SYNOPSIS 


#include <string.h> 
void *memchr(const void *s,int c, size_t n); 


DESCRIPTION 


Thememchr() function scans the first n bytes of the memory area pointed to bys for the character. The first byte to match c 
(interpreted as an unsigned character) stops the operation. 


RETURN VALUE 


Thememchr() function returns a pointer to the matching byte or nut if the character does not occur in the given memory 
area. 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 
index(3), rindex(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3) 
GNU, 12 April 1993 


memcmp 


memcmp— C ompares memory areas 


SYNOPSIS 


#include <string.h> 
int memcmp(const void *sl1, const void *s2, size_t n); 


DESCRIPTION 


The mememp() function compares the first n bytes of thememory areass1 and s2. It returns an integer less than, equal to, or 
greater than zero if s1 isfound, respectively, to be less than, to match, or to be greater than s2. 


RETURN VALUE 


The mememp() function returns an integer less than, equal to, or greater than zero if the firstn bytes of s1 is found, respec- 
tively, to be less than, to match, or be greater than the first n bytes of s2. 
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CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 


bemp(3), strcasecmp(3), stremp(3), strcol1(3), strncmp(3), strncasecmp(3) 
10 April 1993 


memcpy 


memcpy— C opies memory area 


SYNOPSIS 


#include <string.h> 
void *memcpy(void *dest, const void *src, size_t n); 


DESCRIPTION 


Thememcpy() function copiesn bytes from memory areasrc to Memory area dest. The memory areas may not overlap. U se 
memmove(3) if the memory areas do overlap. 


RETURN VALUE 


The memcpy() function returns a pointer to dest. 


CONFORMS T0 
SVID 3, BSD 4,3, 1SO 9899 


SEE ALSO 


beopy(3), memccpy(3), memmove(3), strcpy(3), strncpy(3) 
GNU, 10 April 1993 


memf rob 


memf rob— Frobnicates (encrypts) a memory area 


SYNOPSIS 


#include <string.h> 
void *memfrob(void *s, size_t n); 


DESCRIPTION 


The memfrob() function encrypts the first n bytes of thememory areas by using exclusive or on each character with the 
number 42. T he effect can be reversed by using memfrob() on the encrypted memory area. 


N ote that this function isnot a proper encryption routine as the xor constant is fixed, and is only suitable for hiding strings. 


RETURN VALUE 


The memfrob() function returns a pointer to the encrypted memory area. 
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CONFORMS TO 
The memfrob() function isunique to the Linux C Library and GNU C Library. 


SEE ALSO 


strfry(3) 
GNU, 12 April 1993 


memmem 


memmem— Locates a substring 


SYNOPSIS 


#include <string.h> 
void *memmem(const void *needle, size t needlelen, 
const void *haystack, size_t haystacklen");" 


DESCRIPTION 


The memmem() function finds the first occurrence of the substring need! e of length needi el en in thememory areahaystack of 
length haystacklen. 


RETURN VALUE 


The memmem() function returns a pointer to the beginning of the substring, or NuLt if the substring is not found. 


SEE ALSO 


strstr(3) 
GNU, 11 April 1993 


memmove 


memmove— Copies memory area 


SYNOPSIS 


#include <string.h> 
void *memmove(void *dest, const void *src, size_t n); 


DESCRIPTION 


The memmove() function copiesn bytes from memory areasrc to memory area dest . The memory areas may overlap. 


RETURN VALUE 


The memmove() function returns a pointer to dest. 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 


bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 
GNU, 10 April 1993 
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memset— Fills memory with a constant byte 


SYNOPSIS 


#include <string.h> 
void *memset(void *s,intc, size_t n); 


DESCRIPTION 


The memset () function fills the first n bytes of the memory area pointed to bes with the constant byte c. 


RETURN VALUE 


Thememset() function returns a pointer to the memory areas. 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 
bzero(3), swab(3) 
GNU, 11 April 1993 


mkfifo 


mkfifo— M akes aFIFO special file (anamed pipe) 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/stat.h> 
int mkfifo ( const char *pathname ,mode_t mode ); 


DESCRIPTION 


mkfifo Makes a FIFO special file with name pathname. mode specifies the FIFO ’s permissions. It ismodified by the process's 
umask in the usual way: the permissions of the created file are (mode&umask). 


A FIFO special file is similar to a pipe, except that it is created in a different way. Instead of being an anonymous communi- 
cations channd, aFIFO special file is entered into the filesystem by calling mkfifo. 





After you have created aFIFO special filein this way, any process can open it for reading or writing, in thesame way as an 
ordinary file. H oweve,, it has to be open at both ends simultaneously before you can proceed to do any input or output 
Operations on it. O pening aFIFO for reading normally blocks until some other process opens the same FIFO for writing, 


and vice versa. 
RETURN VALUE 
Thenormal, successful return value from mkfifo is a. |n the case of an error, -1 is returned (in which case, errno is set 
appropriate y). 
ERRORS 
EACCES Oneof the directoriesin pathname did not allow search (execute) permission. 


EEXIST pathname already exists. 


mktenp 


ENAMETOOLONG Either the total length of pathname is greater than PATH_MAX, or an individual 
filename component has a length greater than name_max. In the GN U system, 
there isno imposed limit on overall filename length, but some filesystems may 
place limits on the length of a component. 


ENOENT A directory component in pathname does not exist or isa dangling symbolic 
link. 

ENOSPC The directory or filesystem has no room for the new file. 
ENOTDIR A component used as a directory in pathname is not, in fact, a directory. 
EROFS pathname refers to a read-only filesystem. 

CONFORMS TO 

POSIX.1 
SEE ALSO 


mkfifo(1), read(2), write(2), open(2), close(2), stat(2), umask(2) 
Linux 1.2.13, 3 Septenber 1995 


mkstemp 


mkstemp— Creates a unique temporary file 


SYNOPSIS 


#include <unistd.h> 
int *mkstemp(char *templ ate); 


DESCRIPTION 


Themkstemp() function generates a unique temporary filename from t emp! ate. The last six characters of t empl ate must be 
XXXXxx and these are replaced with a string that makes the filename unique T hefile is then created with mode read/write and 
permissions 0666. 


RETURN VALUE 


The mkstemp() function returns the file descriptor fa of the temporary file 


ERRORS 
EINVAL The last six characters of t emp! ate were not XXXxxx. 
EEXIST Thetemporary file is not unique. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 
mktemp(3), tmpnam(3), tempnam(3), tmpfile(3) 
GNU, 3 April 1993 


mktemp 


mktemp— M akes a unique temporary filename 
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SYNOPSIS 


#include <unistd.h> 
char *mktemp(char *templ ate); 


DESCRIPTION 


The mktemp() function generates a unique tenporary filename from t emp! ate. The last six characters of t emp! ate must be 
XXXXXxX and these are replaced with a string that makes the filename unique 


RETURN VALUE 


The mktemp() function returns a pointer to t emp! ate ON Success, and NULL on failure. 


ERRORS 


EINVAL The last six characters of template were NOt XXXXxx. 


CONFORMS TO 
BSD 4.3. POSIX dictates tmpnam(). 


SEE ALSO 


mkstemp(3), tmpnam(3), tempnam(3), tmptile(3) 
GNU, 3 April 1993 


modf 


modf— Extracts signed integral and fractional values from floating-point number 


SYNOPSIS 


#include <math.h> 
double modf (double x, double *i ptr); 


DESCRIPTION 


The modt() function breaks the argument x into an integral part and a fractional part, each of which has the same sign asx. 
Theintegral part is stored ini ptr. 


RETURN VALUE 


The mod¢() function returns the fractional part of x. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3, 1SO 9899 


SEE ALSO 


frexp(3), 1dexp(3) 
6 June1993 


asctime, ctime, difftime, gmtime, Localtime, mktime 


asctime, ctime, difftime, gmtime, localtime, mktime— Convert date and time to ASCII 


asctime, ctime, difftime, gmtime localtime mktime 


SYNOPSIS 


extern char *tzname[2]; 
void tzset() 
#include <sys/types.h> 


char *ctime(clock) 
const time_t *clock; 


double difftime(time1, timeQ) 
time_t time1; 
time_t timed; 


#include <time.h> 


char *asctime (tm) 
const struct tm *tm; 


struct tm *localtime(clock) 
const time_t *clock; 


struct tm *gmtime(clock) 
const time_t *clock; 





time_t mktime(tm) 
struct tm *tm; 





co... -1z 


DESCRIPTION 


ctime converts a long integer, pointed to by clock, representing the time in seconds since 00:00:00 UTC, January 1, 1970, 
and returns a pointer to a26-character string of the form Thu Nov 24 18:22:48 1986. (Note: UTC is Coordinated U niversal 
Time) All the fields have constant width. 


localtime and gmtime return pointers to tm structures, described in the following paragraphs. localtime corrects for the time 
zone and any time zone adjustments (such as D aylight Saving Time in the U nited States). Before doing so, localtime Calls 
tzset (if tzset has not been called in the current process). After filling in the tm structure, localtime sets the tm_isdst’th 
element of tzname to a pointer to an ASCII string that’s the time zone abbreviation to be used with 1ocaltime’s return value. 


gmtime converts to C oordinated Universal Time 


asctime Converts a time value contained in a tm structure to a26-character string, as shown in the preceding example, and 
returns a pointer to the string. 


mktime converts the broken-down time, expressed as local time, in the structure pointed to by tm into a calendar time value 
with the same encoding as that of the values returned by the time function. T he original values of the tm_wday and tm_yday 
components of the structure are ignored, and the original values of the other components are not restricted to their normal 
ranges. (A positive or zero value for tm_isdst Causes mktime to presume initially that summer time (for example, D aylight 
Saving Time in the U nited States) respectively, is or is not in effect for the specified time A negative value for tm_isdst 
causes the mktime function to attanpt to divinewhehe summer timeis in effect for the specified time.) On successful 
completion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other 
components are set to represent the specified calendar time, but with ther values forced to thar normal ranges, the final 
value of tm_mday isnot set until tm_mon and tm_year are determined. mktime returns the specified calendar time; if the calendar 
time cannot be represented, it returns -1. 
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difftime returns the difference between two calendar times, (ti mel - timed), expressed in seconds. 


Declarations of all the functions and externals, and the tm structure, arein the <time.h> header file The structure (of type) 
struct tmincludesthe following fidds: 


int 
int 
int 
int 
int 
int 
int 
int 
int 


tm_sec; 
tm_min; 
tm_hour; 
tm_mday; 
tm_mon; 
tm_year; 
tm_wday; 
tm_yday; 
tm_isdst; 


char tm_zone; 


long tm_gmtoff; 


The tm_zone and tm_gmtoff fi 


~~r~onr~ onan aS aS arr 


seconds (@ - 60 
minutes (@ - 59 


hours 
day o 
month 


(@ - 23) / 
month (1 - 31) / 
of year (0 - 11) / 


year - 1900 / 


day o 
day o 


week (Sunday = Q) / 
year (0 - 365) / 


is summer time in effect? / 
abbreviation of timezone name / 


offse 


from UTC in seconds / 





idds exist, and are filled in, only if arrangements to do so were made when the library containing 


these functions was created. T here is no guarantee that these fidds will continue to exist in this form in future releases of this 


code. 


Tm_isdst is non-zero if summer timeis in effect. 


Tm_gmtoff is the offset (in seconds) of the time represented from UTC, with positive values indicating east of the Prime 
M eridian. 


FILES 


/usr/local/etc/zoneinfo 


Timezone information directory 


/usr/local/etc/zoneinfo/localtime Local time zone file 


/usr/local/etc/zoneinfo/posixrules 


Used with PO SIX-styleT Zs 


/usr/local/etc/zoneinfo/GMT For UTC leap seconds 


If /usr/local/etc/zoneinfo/GmT is absent, UTC leap seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 


SEE ALSO 


getenv(3), newtzset(3), time(2), tzfile(5) 


NOTES 


Thereturn values point to static data; the data is overwritten by each call. The tm_zone field of areturned struct tm points to 
a static array of characters, which will also be overwritten at the next call (and by calls to tzset). 


Avoid using out-of-range values with mktime when setting up lunch with promptness sticklers in Riyadh. 


tzset 


tzset— Initializes time conversion information 


SYNOPSIS 


void tzset(); 


cc... 


-1z 


tzset 987 


DESCRIPTION 


tzset uses the value of the environment variable 1z to set time conversion information used by localtime.If Tz does not 
appear in the environment, the best available approximation to local wall clock time, as specified by the tzfite(5)-format file 
localtime in the system time conversion information directory, isused by 1localtime. If Tz appears in the environment but its 
valueisanull string, Coordinated Universal Time (UTC) is used (without leap second correction). If Tz appears in the 
environment and its value is not anull string, it is used in one of the following ways: 


If the value begins with a colon, it is used as a pathname of a file from which to read the time conversion information. 


If the value does not begin with a colon, it is first used as the pathname of a file from which to read the time conversion 
information, and, if that file cannot be read, is used directly as a specification of the time conversion information. 


W hen 1z isused asapathname if it begins with a slash, it is used as an absolute pathname otherwise, it is used asa 
pathname relative to a system time conversion information directory. T hefile must bein the format specified in tzfile(5). 


When 1z isused directly as a specification of the time conversion information, it must have the following syntax (spaces 
inserted for clarity): 


std offset[dst[offset][,rule]] 
The dements are as follows: 


std and dst Three or more bytes that are the designation for the standard (std) or 
summe (dst) timezone Only std is required; if dst is missing, then 
summer time does not apply in this locale. U ppercase and lowercase 
letters are explicitly allowed. Any characters except a leading colon (:), 
digits, comma (,), minus (-), plus (+), and ASCII NUL are allowed. 

offset Indicates the value one must add to the local time to arrive at 
Coordinated Universal Time Theoffset has the form: 
hh[E:mm[:ss]] 
The minutes (mm) and seconds (ss) are optional. The hour (hn) is required 
and may beasingle digit. Theoffset following std is required. If no 
offset followsdst, summer time is assumed to be one hour ahead of 
standard time. O ne or more digits may be used; the value is always 
interpreted as a decimal number. The hour must be between zero and 24, 
and the minutes (and seconds)— if present— between zero and 59. If 
preceded by a+", the time zone shall be east of the Prime M eridian; 
otherwise it shall be west (which may be indicated by an optional 


preceding "-"). 
rule Indicates when to change to and back from summer time. Therul e has 
the form: 


date/time ,date/time 


where the first dat e describes when the change from standard to summer 
time occurs and the second date describes when the change back happens. 
Each time fidd describes when, in current local time, the change to the 
othe timeismade 
The format of date is one of the following: 
Thed'th day (0 <=d <=6) of week n of month m of the year (1 <=n 
<=5, 1 <=m <12, where week 5 means “the last ¢ day in month m” 
which may occur in either the fourth or the fifth week). Week 1 
is the first week in which thea th day occurs. D ay zero is Sunday. 

Jn TheJulian dayn (1 <=n <=365). Leap days are not counted; that is, in 
all years— including leap years— February 28 is day 59 and M arch 1 is 
day 60. It is impossible to explicitly refer to the occasional February 29. 
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n T he zero-based Julian day (0 <=n <=365). Leap days are counted, and it 
is possible to refer to February 29. 
Mm. n.d Thea'th day (0 <=d <=6) of week n of month m of the year (1 <=n <=5, 


1 <m <12, where week 5 means “the last ¢ day in month m,” which 
may occur in eather the fourth or the fifth week). W eek 1 isthe first week 
in which thed'th day occurs. D ay zero is Sunday. 

The time has the same format as offset except that no leading sign (“+’ 
or “-”) is allowed. The default, if time isnot given, is 02:00:00. 


If no rule is present in Tz, the rules specified by the tzfile(5)-format file posixrules in the system time conversion 
information directory are used, with the standard and summer time offsets from UTC replaced by those specified by the 
offset valuesin 12. 


For compatibility with System V Release 3.1, a semicolon (;) may be used to separate the rule from the rest of the specifica- 
tion. 


If the Tz environment variable does not specify a tzfile(5)-format and cannot be interpreted as a direct specification, UTC is 
used. 


FILES 
/usr/local/etc/zoneinfo Timezone information directory 
/usr/local/etc/zoneinfo/localtime Local time zone file 
/usr/local/etc/zoneinfo/posixrules Used with PO SIX-style tzs 
/usr/local/etc/zoneinfo/GMT For UTC leap seconds 


If /usr/local/etc/zoneinfo/GmT is absent, UTC leap seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 


SEE ALSO 


getenv(3), newctime(3), time(2), tzfile(5) 


on exit 
on exit— Registers a function to be called at normal program termination 


SYNOPSIS 


#include <stdlib.h> 
int on_exit(void (*function) (int , void *), void *arg); 


DESCRIPTION 


The on_exit() function registers the given function to be called at normal program termination, whether via exit(2) or via 
return from the program's main. The function is passed the argument to exit(3) and the arg argument from on_exit(). 


RETURN VALUE 


The on_exit() function returns the value a if successful; otherwise, the value -1 is returned. 
SEE ALSO 
exit(3), atexit(3) 
GNU, 2 April 1993 
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opendir 
opendir— O pens a directory 


SYNOPSIS 


#include <sys/types.h> 
#include <dirent.h> 
DIR *opendir(const char *name); 


DESCRIPTION 


The opendir() function opens a directory stream corresponding to the directory name, and returns a pointer to the directory 
stream. T he stream is positioned at the first entry in the directory. 


RETURN VALUE 
The opendir() function returns a pointer to the directory stream or NULL if an error occurred. 
ERRORS 
EACESS Permission denied 
EMFILE Too many file descriptors in use by process 
ENFILE Too many files are currently open in the systen 
ENOENT Directory does not exist, orname isan enpty string 
ENOMEM Insufficient memory to complete the operation 
ENOTDIR name iSnot a directory 
CONFORMS TO 
SVID 3, POSIX, BSD 4.3 
SEE ALSO 


open(2), readdir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 
11 June1995 


parsedate 


parsedate— Converts time and date string to number 


SYNOPSIS 


#include <sys/types.h> 
typedef struct_TIMEINFO f 
time_t time; 

long usec; 

long tzone; 

} TIMEINFO; 

time_t 

parsedate(text, now) 

char *text; 

TIMEINFO *now; 


DESCRIPTION 


parsedate converts many common time specifications into the number of seconds since the epoch, that is, a time_t; see 
time(2) 
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parsedate returns thetime, or -1 on error. text isa character string containing thetimeand date now isa pointe to the time 
that should be used for calculating relative dates. If now is NULL, then GetTimeInfo iN libinn(3) is used to obtain the current 
time and time zone 


The character string consists of zero or more specifications of the following form: 


time A time of day, which is of the form hh[:mm[:ss]] [meridian ][zone]OF hhmm 
[meridian ][zone]. If no meridian is specified, hn isinterpreted on a 24-hour 
clock. 

date A specific month and day with optional year. The acceptable formats are 


mm/dd[/yy],yyyy/mm/dd, monthname dd[, yy], dd monthname [yy],and 
day,ddmonthnameyy, ANG day, dd monthname yy. | hedefault year is the current 
year. If the year is less then 100, then 1900 is added to it; if it isless then 21, 
then 2000 is added to it. 


relative time A specification rdative to the current time. The format iSnumber unit; 
acceptable units are year, month, week, day, hour, minute (Or min), and second 
(or sec). The unit can be specified as a singular or plural, asin 3 weeks. 


The actual date is calculated according to the following steps. First, any absolute date or time is processed and converted. 
Using that time as the base, day-of-week specifications are added. N ext, rdative specifications are used. If a date or day is 
specified, and no absolute or relative timeis given, midnight is used. Finally, a correction is applied so that the correct hour 
of the day is produced after allowing for D aylight Savings T ime differences. 


parsedate ignores case when parsing all words; unknown words are taken to be unknown time zones, which are treated as 
GMT. The names of the months and days of the week can be abbreviated to their first three letters, with optional trailing 
period. Periods are ignored in any time zone or meridian values. 


BUGS 


parsedate does not accept all desirable and unambiguous constructions. Senantically incorrect dates such as “February 31” 
are accepted. 


Daylight Savings Time is always taken as a one-hour change that is wrong for some places. The D aylight Savings Time 
correction can get confused if parsing a time within an hour of when the reckoning changes, or if given a partial date. 


HISTORY 


Originally written by Steven M. Bellovin (smb@research. att.com) while at the U niversity of N orth Carolina at Chapd H ill 
and distributed under the name getdate. 


A major overhaul was done by Rich $alz (rsalz@bbn.com) and Jim Berets (jberets@bbn.com) in August, 1990. 


It was further revised (primarily to remove obsolete constructs and time zone names) a year later by Rich (now 
rsalz@osf.org) for |nterN etN ews, and the name was changed. 


SEE ALSO 


date(1), ctime(3), 1ibinn(3), time(2) 


perror 


perror— Prints a system error message 


SYNOPSIS 


#include <stdio.h> 
void perror(const char *s); 


#include <errno.h> 


popen, pclose 


const char *sys_errlist[]; 
int sys_nerr; 


DESCRIPTION 


Theroutine perror() produces a message on the standard error output, describing the last error encountered during a call to 
a system or library function. The argument string s is printed first, then a colon and a blank, then the message and a newline 
To be of most use, the argument string should include the name of the function that incurred the error. Theerror number is 
taken from the external variable errno, which is set when errors occur but not cleared when nonerroneous calls are made. 


The global error list sys_errlist[] indexed by errno can be used to obtain the error message without the newline The largest 
message number provided in the table is sys_nerr -1. Be careful when directly accessing this list because new error values 
may not have been added to sys errlist[]. 


When asystem call fails, it usually returns -1 and sets the variable errno to a value describing what went wrong. (T hese values 
can be found in <errno.h>.) M any library functions do likewise The function perror() serves to translate this error code into 
human-readable form. N ote that errno is undefined after a successful library call. T his call may wel change this variable 
even though it succeeds, for example, because it internally used some othe library function that failed. T hus, if a failing call 
isnot immediate y followed by a call to perror,the value of errno should be saved. 


CONFORMS TO 
ANSI C, BSD 4.3, POSIX, X/OPEN 


SEE ALSO 


strerror(3) 


16 May 1996 


popen, pclose 


popen, pclose— Process |/O 


SYNOPSIS 


#include <stdio.h> 
FILE *popen(const char *command, const char *type); 


int pclose(FILE *stream); 


DESCRIPTION 


The popen() function opens a process by creating a pipe, forking, and invoking the shell. Because a pipe is by definition 
unidirectional, the type argument may specify only reading or writing, not both; the resulting stream is correspondingly 
read-only or write-only. 


The command argument is a pointer to a null-terminated string containing a shal command line T his command is passed to 
/bin/sh using the -c flag; interpretation, if any, is performed by the shdl. Themode argument is a pointer to anull- 
terminated string which must be ather r for reading or w for writing. 


The return value from popen() isanormal standard I/O stream in all respects save that it must be closed with pclose() rather 
than fclose(). Writing to such a stream writes to the standard input of the command; the command's standard output is the 
same as that of the process that called popen(), unless this is altered by the command itself. Conversely, reading from a 
“popeed” stream reads the command's standard output, and the command's standard input is the same as that of the 
process that called popen. 
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N ote that output popen streams are fully buffered by default. 


The pclose function waits for the associated process to terminate and returns the exit status of the command as returned by 
wait4. 


RETURN VALUE 
The popen function returns NnuLL if the fork(2) or pipe(2) calls fail, or if it cannot allocate memory. 


The pclose function returns -1 if stream isnot associated with a “popened” command, if stream already “pclosed,” or if wait4 
returns an error. 


ERRORS 


The popen function does not rdiably set errno. (Is this true for Linux?) 


BUGS 


The standard input of acommand opened for reading shares its seek offset with the process that called popen(); therefore, if 
the original process has done a buffered read, the command's input position may not be as expected. Similarly, the output 
from acommand opened for writing may become intermingled with that of the original process. T he latter can be avoided 
by calling ff1ush(3) before popen. 


Failure to execute the shal isindistinguishable from the shdll’s failure to execute command, or an immediate exit of the 
command. The only hint is an exit status of 127. (Is this true under Linux?) 


The function popen() always calls sh, never calls csh. 


HISTORY 
A popen() and a pclose() function appeared in Version 7 AT&T UNIX. 


SEE ALSO 
fork(2), sh(1), pipe(2), wait4(2), fflush(3), fclose(3), fopen(3), stdio(3), system(3), fclose(3), fopen(3), stdio(3), system(3). 
BSD man page 17 M ay 1996 


printf, fprintf, sprintf, snprintf, vprintf, vfprintf, 
vsprintf, vsnprintt 


printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf— Formatted output conversion 


SYNOPSIS 


#include <stdio.h> 


int printf( const char *format, ...); 

int fprintf( FILE *stream, const char *format, ...); 

int sprintf( char *str, const char *format, ...); 

int snprintf( char *str, size_t size, const char *format, ...); 





#include <stdarg.h> 


int vprintf( const char *format ,va_list ap); 

ant vfprintf( FILE *stream, const char *format ,va_list ap); 

int vsprintf( char *str, char *format, va_list ap); 

int vsnprintf( char *str, size_t size, char *format ,va_list ap); 


printf, forintf, sorintf, nprintf, vprintf, vfprintf, vsprintf, viprintf 
DESCRIPTION 


The printt family of functions produces output according to afor mat, as described in the following paragraphs. The 
functions printf and vprintf write output to stdout, the standard output stream; fprintf and vfprintf write output to the 
given output stream; sprintf, snprintf, vsprintf, and vsnprintf write to the character string str. 


T hese functions write the output under the control of aformat string that specifies how subsequent arguments (or arguments 
accessed via the variable length argument facilities of stdarg(3)) are converted for output. 


T hese functions return the number of characters printed (not including the trailing \o used to end output to strings). 
snprintf and vsnprintf do not write more than size bytes (including the trailing \o), and return -1 if the output was 
truncated due to this limit. 


Theformat string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the 
output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each 
conversion specification is introduced by the character ». The arguments must correspond properly (after type promotion) 
with the conversion specifier. After the%, zero or more of the following flags appear in sequence: 


# Specifying that the value should be converted to an alternate form. For, d, i, n, p, s, andu 
conversions, this option has no effect. For o conversions, the precision of the number is increased to 
force the first character of the output string to a zero (except if azero value is printed with an explicit 
precision of zero). For x and x conversions, a non-zero result has the string ox (or ox for x 
conversions) prepended to it. Fore, , f, g, and a conversions, the result will always contain a decimal 
point, even if no digits follow it (normally, a decimal point appears in the results of those conversions 
only if adigit follows). For g and c conversions, trailing zeros are not renoved from the result as they 
would otherwise be. 

() Specifying zero padding. For all conversions except n, the converted value is padded on the left with 
zeros rather than blanks. If a precision is given with anumeric conversion (4, i, 0, u, i, x, and x), the 
0 flag isignored. 

- (a negative field width flag) Indicates the converted value is to be left adjusted on the field boundary. 
Except for n conversions, the converted value is padded on the right with blanks, rather than on the 
left with blanks or zeros. A - overrides ao if both are given. 

a (a space) Specifying that a blank should be left before a positive number produced by a signed 
conversion (d, e, E, f, g, G, Or i). 

+ Specifying that a sign always be placed before a number produced by asigned conversion. 

A + overides a space if both are used. 

Specifying that in anumerical argument the output is to be grouped if the locale information 
indicates any. N ote that many versions of gcc cannot parse this option and will issue a warning. 

An optional decimal digit string specifying a minimum fied width. If the converted value has fewer 
characters than the fidd width, it will be padded with spaces on the left (or right, if the left- 
adjustment flag has been given) to fill out the field width. 

An optional precision, in the form of a period (.) followed by an optional digit string. If the digit 
string is omitted, the precision is taken as zero. Thisgivesthe minimum number of digits to appear 
ford, i, 0, u, x, and x conversions; the number of digits to appear after the decimal point for e, e, and 
f conversions, the maximum number of significant digits for g and @ conversions; or the maximum 
number of characters to be printed from a string for s conversions. 

The optional character h, specifying that afollowing q, i, o, u, x, or x conversion corresponds to a 
short int or unsigned short int argument, or that a following n conversion corresponds to a pointer 
to ashort int argument. 

The optional character 1 (ell) specifying that a following q, i, o, u, x, or x conversion applies to a 
pointer to along int or unsigned long int argument, or that a following n conversion corresponds to 
a pointer to a long int argument. Linux provides a non-AN Sl-compliant use of two 1 flags asa 
synonym to q or L. T hus, 11 can be used in combination with float conversions. T his usageis, 
however, strongly discouraged. 
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The character L specifying that a following e, E, f, g, or G conversion corresponds to a long double 
argument, or a following d, i, 0, u, x, or x conversion corresponds to a long long argument. N ote that 
long long isnot specified in AN SI C and therefore not portable to all architectures. 

The optional character q. T his is equivalent to L. See the “Standards” and “Bugs” sections for 
comments on the use of 11, L, and q. 

A z character specifying that the following integer (a, i, 0, u, i, x, and x) conversion corresponds to a 
size_t argument. 

A character that specifies the type of conversion to be applied. 


A field width or precision, or both, may be indicated by an asterisk « instead of a digit string. In thiscase, an int argument 
supplies the fidd width or precision. A negative fidd width is treated as a left adjustment flag followed by a positive field 
width; a negative precision is treated as though it were missing. 


The conversion specifiers and their meanings are as follows: 


diouxXx 


eE 


© 


The int (or appropriate variant) argument is converted to signed decimal (a and i), 
unsigned octal (0), unsigned decimal (u), or unsigned hexadecimal (x and x) notation. The 
letters abcdef are used for x conversions; the letters ascper are used for x conversions. T he 
precision, if any, gives the minimum number of digits that must appear; if the converted 
value requires fewer digits, it is padded on the left with zeros. 

The double argument is rounded and converted in the style [-]d.ddde\dd where thee is 
one digit before the decimal-point character and the number of digits after it is equal 

to the precision; if the precision is missing, it istaken as 6; if the precision is zero, no 
decimal-point character appears. An € conversion uses the letter E (rather than e) to 
introduce the exponent. T he exponent always contains at least two digits; if the value is 
zero, the exponent is 00. 

The double argument is rounded and converted to decimal notation in the style 

[-]ddd. ddd, where the number of digits after the decimal-point character is equal to 

the precision specification. If the precision is missing, it is taken as6; if the precision is 
explicitly zero, no decimal-point character appears. If a decimal point appears, at least one 
digit appears before it. 

The double argument is converted in style f or e (or E for @ conversions). T he precision 
specifies the number of significant digits. If the precision is missing, 6 digits are given; if 
the precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is 
less than negative 4 or greater than or equal to the precision. T railing zeros are ranoved 
from the fractional part of the result; a decimal point appears only if it is followed by at 
least one digit. 

The int argument is converted to an unsigned char, and the resulting character is written. 
The char * argument is expected to bea pointer to an array of character type (pointer to a 
string). Characters from the array are written up to (but not including) a terminating nuL 
character; if a precision is specified, no more than the number specified are written. If a 
precision is given, no null character need be present; if the precision isnot specified, or is 
greater than the size of the array, the array must contain a terminating nut character. 

The void * pointer argument is printed in hexadecimal (as if by s#x or %#1x). 


The number of characters written so far is stored into the integer indicated by the int * 
(or variant) pointer argument. No argument is converted. 


A *iswritten. No argument is converted. The complete conversion specification is%%. 


In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the 
fidd width, the fidd is expanded to contain the conversion result. 


printf, forintf, sorintf, nprintf, vprintf, vfprintf, vsprintf, viprintf 
EXAMPLES 


To print a date and timein the form “Sunday, J uly 3, 10:02,” where weekday and month are pointers to strings: 
#include <stdio.h> 


fprintf(stdout, "%s, %s %d, %.2d:%.2d\n", 
weekday, month, day, hour, min); 


To print to five decimal places: 


#include <math.h> 
#include <stdio.h> 
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0)); 


To allocate a128-byte string and print into it: 


#include <stdio.h> 
#include <stdlib.h> 
#include <stdarg.h> 


char *newfmt(const char *fmt, ...) 
{ 
char *p; 
va_list ap; 
if ((p = malloc(128)) == NULL) 
return (NULL); 
va_start(ap, fmt); 
(void) vsnprintf(p, 128, fmt, ap); 
va_end(ap); 
return (p); 


SEE ALSO 


printf(1), scant (3) 


STANDARDS 
The fprintf, printf, sprintf, vprintf, vfprintf, and vsprintf functions conform to AN SI C3.159-1989 (“ANSI C”). 
Theq flag isthe BSD 4.4 notation for 1ong long, while 11 or the usage of L in integer conversions isthe GN U notation. 
The Linux version of these functions is based on the GN U 1ibio library. Take a look at the info documentation of GNU 
libe (glibc-1.08) for a more concise description. 

BUGS 
Some floating point conversions under Linux cause memory leaks. 


All functions are fully AN SI C3.159-1989 conformant, but provide the additional flags q, z, and ' aswell as an additional 
behavior of thet and 1 flags. T he latter may be considered to be a bug, as it changes the behavior of flags defined in AN SI 
C3.159-1989. 


The effect of padding the %p format with zeros (either by thee flag or by specifying a precision), and the benign effect (that 
is, none) of the # flag on %n and %p conversions, as well as nonsensical combinations that are not standard; such combinations 
should be avoided. 


Some combinations of flags defined by AN SI C are not making sense (for example, xLd). W hile they may have a wdl-defined 
behavior on Linux, this need not to beso on other architectures. Therefore, it usually is better not to use flags that are not 
defined by ANSI C at all; in other words, that use q instead of L in combination with diouxx conversionsor 11. 


The usage of q isnot the same ason BSD 4.4, as it may be used in float conversions equivalently to L. 
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Because sprintf and vsprintf assume an infinitely long string, callers must be careful not to overflow the actual space; this is 
often impossible to assure 
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psignal 
psignal— Prints signal message 


SYNOPSIS 


#include <signal.h> 
void psignal(int sig, const char *s); 
extern const char *const sys_siglist[] 


DESCRIPTION 


The psignal() function displays a message on stderr consisting of the string s, a colon, a space, and a string describing the 
signal number sig. If sig isinvalid, the message displayed will indicate an unknown signal. 


The array sys siglist holds the signal description strings indexed by signal number. 


RETURN VALUE 


The psignal() function returns no value. 


CONFORMS TO 
BSD 4,3 


SEE ALSO 


perror(3), strsignal(3) 
GNU, 13 April 1993 


putenv 


putenv— Changes or adds an environment variable 


SYNOPSIS 


#include <stdlib.h> 
int putenv(const char *string); 


DESCRIPTION 


The putenv() function adds or changes the value of environment variables. The argument string is of theform name = value. 
If name does not already exist in the environment, then string is added to the environment. If name does exist, then the value 
Of name in the environment is changed to value. 


RETURN VALUE 


The putenv() function returns zero on success, or -1 if an error occurs. 


ERRORS 


ENOMEM Insufficient space to allocate new environment 


fputc, fouts, putc, putchar, puts 997 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3 


SEE ALSO 


getenv(3), setenv(3), unsetenv(3) 


GNU, 8 April 1993 


putpwent 


putpwent— W rites a password file entry 


SYNOPSIS 


#include <pwd.h> 

#include <stdio.h> 

#include <sys/types.h> 

int putpwent(const struct passwd *p,FILE*stream); 


DESCRIPTION 
The putpwent() function writes a password entry from the structure p in the file associated with stream. 
The passwd structure is defined in <pwd.h> as follows: 


struct passwd { 


char *pw_name; /* user name */ 
char *pw_passwd; /* user password */ 
uid_t  pw_uid; /* user id */ 
gid t pw_gid; /* group id */ 
char *pw_gecos; /* real name */ 
char *ow_dir; /* home directory */ 
char *pw_shell; /* shell program */ 
hs 
RETURN VALUE 
The putpwent() function returns on success, or -1 if an error occurs. 
ERRORS 
EINVAL Invalid (NULL) argument given 
CONFORMS TO 
SVID 3 
SEE ALSO 


fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), getpw(3) 
GNU, 9 April 1993 


fputc, fputs, putc, putchar, puts 


fputc, fputs, putc, putchar, puts— O utput of characters and strings 
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SYNOPSIS 


#include <stdio.h> 
int fputc(int c ,FILE*stream); 
int fputs(const char *s ,FILE*stream); 
int putc(int c,FILE *stream); 
int putchar(int c); 
int puts(char *s); 
int ungetc(int c,FILE *stream); 
DESCRIPTION 
fputc() writes the character c, cast to an unsigned char, to stream. 
fputs() writes the string s to stream, without its trailing \o. 
pute() is equivalent to fputc() except that it may be implemented as a macro that evaluates stream morethan once. 
putchar(c); iS equivalent to putc(c,stdout). 
puts() writes the strings and a trailing newlineto stdout. 
Calls to the functions described here can be mixed with each other and with calls to other output functions from thestdio 
library for the same output stream. 
RETURN VALUES 


fputc(), putc(), and putchar() return the character written as an unsigned char cast to an int or EOF On error. 
puts() and fputs() return anon-negative number on success, Or EOF On error. 


CONFORMS TO 
ANSIC, POSIX.1 


BUGS 


It is not advisable to mix calls to output functions from the staio library with low-leve calls to write() for the file descriptor 
associated with the same output stream; the results will be undefined and very probably not what you want. 


SEE ALSO 
write(2), fopen(3), fwrite(3), scanf(3), gets(3), fseek(3), ferror(3) 
GNU, 4 April 1993 


qi0 
qio— Quick I/O part of InterN etN ews library 
SYNOPSIS 


#include "qio.h" 

QIOSTATE * 

QIOopen(name, size) 

char *name; 

int size; 

QIOSTATE * Q10fdopen(fd, size) 
int fd; 

int size; 

void QI0close(qp) 

QIOSTATE *qp; 


char * QIOread(qp) 
QIOSTATE *qp; 

int QIOlength(qp) 
QIOSTATE *qp; 

int Q10toolong(qp) 
QIOSTATE *qp; 

int QI0error(qp) 
QIOSTATE *qp; 

int QI0tell(qp) 
QIOSTATE *qp; 

int QIOrewind(qp) 
QIOSTATE *qp; 

int QI0fileno(qp) 
QIOSTATE *qp; 


DESCRIPTION 


The routines described in this manual page are part of the InterN etN ews library, 1ibinn(3). T hey are used to provide quick 
read access to files. The letters ato stand for Quick I/O. 


Ql0open opens thefilename for reading. It usesa buffer of size bytes, which must also be larger then the longest expected line. 
The header file defines the constant a1o_BUFFER as a reasonable default. If size is zero, then aroopen will call stat(2) and use 
the returned block size; if that fails it will use ato_BuFFER. It returnS NULL On error, or apointer to ahandle to be used in other 
Calls. alofdopen performs the same function except that fd refers to an already-open descriptor. 


Ql0close closes the open file and rdeases any resources used by it. 


QlOread returns a pointer to the next linein the file The trailing newline will be replaced with a \o. If Eor is reached, an error 
occurs, or if thelineis longer than the buffer, aloread returns NULL. 


After a successful call to at0read, Q101length will return the length of the current line 


The functions atotoolong and aloerror can be called after atoread returns NULL to determine if there was an error, or if the 
line was too long. If atotoolong returns non-zero, then the current line did not fit in the buffer, and the next call to atoread 
will try read the rest of the line Long lines can only be discarded. If atoerror returns non-zero, then aserious!/O error 
occurred. 


arote11 returns the 1seek(2) offset at which the next line will start. 

Ql0rewind sets the read pointer back to the beginning of the file 

Ql0fileno returns the descriptor of the open file 

QIOlength, Q10toolong, Q10error, Q10te11, and al0fileno are implemented as macros defined in the header file 


EXAMPLE 


QIOSTATE *h; 
long offset; 
char *p; 
h = QIOopen("/etc/motd", QIO_BUFFER) ; 
for (offset = Q10tell(h); (p = QIOread(h)) != NULL; offset = QIOtell(h)) 
printf("At %ld, %s\n", offset, p); 
if (QIOerror(h)) { 
perror("Read error"); 
exit(1); 
} 
QI0close(h); 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 
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qsort 


qsort— Sorts an array 


SYNOPSIS 


#include <stdlib.h> 
void qsort(void *base, size t nmemb, size_t size ,int(*compar ) 
(const void *, const void *)); 


DESCRIPTION 
The qsort() function sorts an array with nmemb aements of size si ze.T he base argument points to the start of the array. 


The contents of the array are sorted in ascending order according to a comparison function pointed to by compar, which is 
called with two arguments that point to the objects being compared. 


The comparison function must return an integer less than, equal to, or greater than zero if thefirst argument is considered to 
be respectively less than, equal to, or greater than the second. If two members compare as equal, thar order in the sorted 
array is undefined. 


RETURN VALUE 


Thegqsort() function returns no value. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3,1SO 9899 


SEE ALSO 


sort(1) 


GNU, 29 March 1993 


raise 


raise— Sends a signal to the current process 


SYNOPSIS 


#include <signal.h> 
int raise (int sig); 


DESCRIPTION 
The raise function sends a signal to the current process. It is equivalent to 
kill(getpid() ,sig) 


RETURN VALUE 


Zero on success, non-zero for failure. 


CONFORMS TO 
ANSIC 


SEE ALSO 
kill(2), signal(2), getpid(2) 
GNU, 31 Augut 1995 


random, srandom, initstate satstate 


rand, srand 


rand, srand— Random number generator 


SYNOPSIS 


#include <stdlib.h> 
int rand(void) ; 
void srand(unsigned int seed); 


DESCRIPTION 
The rand() function returns a pseudo-random integer between o and RAND_MAX. 


The srand() function setsits argument as the seed for a new sequence of pseudo-random integers to be returned by rand(). 
T hese sequences are repeatable by calling srand() with thesameseed value. 


If no seed value is provided, the rand() function is automatically seeded with a value of 1. 


RETURN VALUE 
The rand() function returns a value between @ and RAND MAX. The srand() returns no value. 
NOTES 


The versions of rand() and srand() in the Linux C Library use the same random number generator as random() and 
srandom(), SO the lower-order bits should be as random as the higher-order bits. H owever, on older rana() implementations, 
the lower-order bits are much less random than the higher-order bits. 


In Numerical Recipesin C: TheArt of Scientific Computing (William H. Press, Brian P. Flannery, Saul A. T eukolsky, William 
T. Vetterling; N ew York: Cambridge U niversity Press, 1990, first ed, p. 207), the following comments are made: 


“If you want to generate a random integer between 1 and 10, you should always do it by 
j=1+(int) (10.0*rand()/(RAND+MAX+1 0) ) ; 

and never by anything resembling 

j=1+((int) (1000000.0*rand()) % 10); 

(which uses lower-order bits).” 


Random-number generation isacomplex topic. The numerical Recipes in Cc book (see preceding reference) provides an 
excdlent discussion of practical random-number generation issues in Chapter 7, “Random N umbers.” 


For amore theoretical discussion that also covers many practical issues in depth, please see C hapter 3, “Random Numbes,” 
in Donald E. Knuth’sT heArt of Computer Programming, Volume2 (Seminumerical Algorithms), 2nd ed.; Reading, 
M assachusetts: Addison-W esley Publishing Company, 1981. 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 


random(3), srandom(3), initstate(3), setstate(3) 


GNU, 18 May 1995 


random, srandom, initstate, setstate 


random, srandom, initstate, setstate— Random number generator 


Part III: Library Functions 


SYNOPSIS 


#include <stdlib.h> 

long int random(void) ; 

void srandom(unsigned int seed); 

char *initstate(unsigned int seed, char *state,int n); 
char *setstate(char *state); 


DESCRIPTION 


The random() function uses a nonlinear additive feedback random number generator employing a default table of size 31 long 
integers to return successive pseudo-random numbers in the range from o to RAND_MAx. T he period of this random number 
generator is very large, approximately 16*((2**31)-1). 


The srandom() function sets its argument as the seed for anew sequence of pseudo-random integers to be returned by 
random(). T hese sequences are repeatable by calling srandom() with the same seed value. If no seed value is provided, the 
random() function is automatically seeded with a value of 1. 


The initstate() function allows a state array st ate to beinitialized for use by random().T he size of the state array n is used by 
initstate() to decide how sophisticated a random number generator it should use— the larger the state array, the better the 
random numbers will be. seed isthe seed for the initialization, which specifies a starting point for the random number 
sequence, and provides for restarting at the same point. 


The setstate() function changes the state array used by the random() function. The state array st ate isused for random 
number generation until the next call to initstate() Or setstate(). state must first have been initialized using initstate(). 


RETURN VALUE 


The random() function returns a value between a and RAND MAX. The srandom() function returns no value. The initstate() 
and setstate() functions return a pointer to the previous state array. 


ERRORS 


EINVAL A state array of less than 8 bytes was specified to initstate(). 


NOTES 


Current “optimal” values for the size of the state array n are 8, 32, 64, 128, and 256 bytes; other amounts will be rounded 
down to the nearest known amount. Using less than 8 bytes will cause an error. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 
rand(3), srand(3) 


GNU, 28 March 1993 


readdir 


readdir— Reads a directory 


SYNOPSIS 


#include <sys/types.h> 
#include <dirent.h> 
struct dirent *readdir(DIR *dir); 


readv, writev 
DESCRIPTION 


The readdir() function returns a pointer to a dirent structure representing the next directory entry in the directory stream 
pointed to by dir. It returns NULL on reaching the end-of-file or if an error occurred. 


The data returned by readdir() is overwritten by subsequent calls to readdir() for the same directory stream. 
According to PO SIX, the dirent structure containsa field char_d_name[] of unspecified size, with at most namE_max characters 
preceding the terminating null character. U se of other fields will harm the portability of your programs. 

RETURN VALUE 


The readdir() function returns a pointer to adirent structure, or NULL if an error occurs or end-of-file is reached. 


ERRORS 


EBADF Invalid directory stream descriptor dir 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3 


SEE ALSO 
read(2), opendir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 
22 April 1996 


readv, writev 


readv, writev— Reads or writes data into multiple buffers 


SYNOPSIS 


#include <sys/uio.h> 

int readv(int filedes, const struct iovec *vector, 
size_t count); 

int writev(int filedes, const struct iovec *vector, 
size_t count); 


DESCRIPTION 


The readv() function reads count blocks from the file associated with the file descriptor fi! edes into the multiple buffers 
described by vector. 


Thewritev() function writes at most count blocks described by vector to the file associated with the file descriptor til edes. 
The pointer vector points to astruct iovec defined in <sys/uio.h>as 


struct iovect 

{ 

void *iovbase; /* Starting address */ 
size_t iov_len; /* Number of bytes */ 
b; 


Buffers are processed in the order vector[0], vector[1], ... vector[count]. 
The readv() function works just like read(2) except that multiple buffers are filled. 
Thewritev() function works just like write(2) except that multiple buffers are written out. 


RETURN VALUES 


The readv() function returns the number of bytes or -1 on error; the writev() function returns the number of bytes written. 
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ERRORS 


The readv() and writev() functions can fail and set errno to the following values: 


EBADF fd isnot a valid file descriptor. 
EINVAL fa is unsuitable for reading (for readv()) or writing (for writev()). 
EFAULT buf is outside the processes’ address space. 
EAGAIN N onblocking1!/O had been selected in the open() call, and reading or writing could not be 
done immediately. 

EINTR Reading or writing was interrupted before any data was transferred. 

CONFORMS TO 

unknown 
BUGS 


It isnot advisable to mix calls to functions like readv() Or writev(), which operate on file descriptors, with the functions 
from the stdio library; the results will be undefined and probably not what you want. 


SEE ALSO 


read(2), write(2) 
GNU, 25 April 1993 


realpath 


realpath— Returns the canonicalized absolute pathname 


SYNOPSIS 


#include <sys/param.h> 
#include <unistd.h> 
char *realpath(char *path, char resolved _path[]); 


DESCRIPTION 


realpath expands all symbolic links and resolves references to /./, /../ and extra / characters in the null-terminated string 
named by path and stores the canonicalized absolute pathname in the buffer of sizemaxPATHLEN Named by resolved_path. The 
resulting path will have no symbolic link, /./, or /../ components. 


RETURN VALUE 
If thereisno error, it returns a pointer to the resolved_path. 


O therwise, it returns a NULL pointer and places in resolved_path the absolute pathname of the path component that could not 
be resolved. The global variable errno is set to indicate the error. 


ERRORS 
ENOTDIR A component of the path prefix is not a directory. 
EINVAL The pathname contains a character with the high-order bit set. 
ENAMETOOLONG A component of a pathname exceeded maxnawLen characters, or an entire path 
name exceeded MAXPATHLEN Characters. 
ENOENT The named file does not exist. 
EACCES Search permission is denied for acomponent of the path prefix. 
ELOOP Too many symbolic links were encountered in translating the pathname 


EI0 An I/O error occurred while reading from the filesysten. 


regcomp, regexec, regerror, regfree 


SEE ALSO 


readlink(2), getcwd(3) 
GNU, 29 July 1994 


Re comp, re_exec 


re_comp, re_exec— BSD regex functions 


SYNOPSIS 


#include <regex.h> 
char *re comp(char *regex); 
int re exec(char *string); 


DESCRIPTION 


re_comp iS used to compile the null-terminated regular expression pointed to by regex. The compiled pattern occupies a static 
area, the pattern buffer, which is overwritten by subsequent use of re_comp. If regex iS NULL, NO Operation is performed and 
the pattern buffer’s contents are not altered. 


re_exec iS used to assess whether the null-terminated string pointed to by string matches the previously compiled regex. 


RETURN VALUE 


re_comp returns NULL on successful compilation of regex; otherwise, it returns a pointer to an appropriate error message. 





re_exec returns 1 for a successful match, zero for failure. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 
regex(7), GNU regex manual 
Linux, 14 July 1995 


regcomp, regexec, regerror, regfree 


regcomp, regexec, regerror, regfree— PO SIX regex functions 


SYNOPSIS 


#include <regex.h> 

int regcomp(regex_t *preg, const char *regex ,int cflags); 

int regexec(const regex_t *preg, const char *string, size_t nmatch, regmatch_t pmatch[], int eflags); 
size_t regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size); 

void regfree(regex_t *preg); 


PO SIX REGEX COMPILING 
regcomp iS used to compilea regular expression into a form that is suitable for subsequent regexec Searches. 


regcomp is supplied with preg, a pointer to apattern buffer storage area; regex, a pointer to the null-terminated string; and 
cflags, flags used to determine the type of compilation. All regular expression searching must be done via a compiled pattern 
buffer; thus, regexec must always be supplied with the address of a regcomp initialized pattern buffer. 
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cflags may be the bitwise or of one or more of the following: 


REG_EXTENDED Use POSIX extended regular expression syntax when interpreting regex. If 
not set, PO SIX basic regular expression syntax is used. 

REG_ICASE Do not differentiate case. Subsequent regexec searches using this pattern 
buffer will be case insensitive. 

REG_NOSUB Support for substring addressing of matches is not required. Thenmatch and 


pmatch parameters to regexec are ignored if the pattern buffer supplied was 
compiled with this flag set. 

REG_NEWLINE M atch-any-character operators don’t match anewline A nonmatching list 
([*...]) not containing a newline matches a newline. M atch-beginning-of- 
line operator (~) matches the enpty string immediately after a newline, 
regardless of whether ef! ags, the execution flags of regexec, contains 
REG_NOTBOL. M atch-end-of-line operator ($) matches the empty string 
immediatey before a newline, regardless of whether ef! ags contains 
REG_NOTEOL. 


PO SIX REGEX MATCHING 


regexec iS used to match anull-terminated string against the precompiled pattern buffer, preg. nmatch and pmatch are used to 
provide information regarding the location of any matches. ef! ags may be the bitwise or of oneor both of REG_NoTBOL and 
REG_NOTEOL, which cause changes in matching behavior described in the following list. 


REG_NOTBOL The match-beginning-of-line operator always fails to match (but see the 
compilation flag REG_NEWLINE, in the preceding subsection). This flag may be used 
when different portions of a string are passed to regexec and the beginning of the 
string should not be interpreted as the beginning of the line. 

REG_NOTEOL The match-end-of-line operator always fails to match (but see the compilation 
flag REG_NEWLINE, in the preceding subsection). 


BYTE OFFSETS 


Unless reg_NosuB was set for the compilation of the pattern buffer, it is possible to obtain substring match addressing 
information. pmat ch must be dimensioned to have at least nmat ch dements. T hese are filled in by regexec with substring 
match addresses. Any unused structure dements will contain the value -1. 


The regmatch_t structure that is the type of pmat ch is defined in regex.h: 


typedef struct 
{ 
regoff_t rm_so; 
regoff_t rm_eo; 
} regmatch_t; 


Each rm_so element that is not -1 indicates the start offset of the next largest substring match within the string. T he relative 
rm_eo element indicates the end offset of the match. 


PO SIX ERROR REPORTING 


regerror iS used to turn the error codes that can be returned by both regcomp and regexec into error message strings. 


regerror iS passed the error code, err code; the pattern buffer, preg; a pointer to a character string buffer, err buf ; and the size 
of thestring buffer, errbuf_size. It returns the sizeof theerrbuf required to contain the null-terminated error message string. 
If both errbuf and errbuf_size arenon-zero, errbuf iSfilled in with thefirst errbuf_size - 1 characters of the error message 
and aterminating null. 


remove 
POSIX PATTERN BUFFER FREEING 


Supplying regfree with a precompiled pattern buffer, preg will free the memory allocated to the pattern buffer by the 
compiling process, regcomp. 


RETURN VALUE 
regcomp returns zero for a successful compilation or an error code for failure. 
regexec returns zero for asuccessful match or REG_NoMATCH for failure. 


ERRORS 


The following errors can be returned by regcomp: 


REG_BADRPT Invalid use of repetition operators, such as using « as the first character 
REG_BADBR Invalid use of back reference operator 
REG_EBRACE Unmatched brace interval operators 
REG_EBRACK Unmatched bracket list operators 
REG_ERANGE Invalid use of the range operator; for example, the ending point of the range 
occurs prior to the starting point 

REG_ECTYPE Unknown character class name 
REG_EPAREN Unmatched parenthesis group operators 
REG_ESUBREG Invalid back reference to a subexpression 
REG_EEND Non-specific error 
REG_ESCAPE Invalid escape sequence 
REG_BADPAT Invalid use of pattern operators such as group or list 
REG_ESIZE Compiled regular expression requires a pattern buffer larger than 64K b 
REG_ESPACE The regex routines ran out of memory 

CONFORMS TO 

POSIX 
SEE ALSO 


regex(7), GNU regex manual 
Linux, 13 July 1994 


remove 


remove— D eletes anameand possibly the file to which it refers 


SYNOPSIS 


#include <stdio.h> 
int remove(const char *pathname); 


DESCRIPTION 


remove deletes aname from the filesystem. If that name was the last link to afile and no processes have the file open, the file 
is ddeted and the spaceit was using is made available for reuse. 


If the name was the last link to a file but any processes still have the file open, the file will remain in existence until the last 
file descriptor referring to it is closed. 
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If the name referred to a symbolic link, the link is renoved. 


If the name referred to a socket, fifo, or device, thename for it isranoved, but processes that have the object open may 


continue to use it. 


RETURN VALUE 


On success, zero is returned. On aeror, -1 iSreturned, and errno is set appropriately. 


ERRORS 


EFAULT 
EACCES 


EPERM 


ENAMETOOLONG 
ENOENT 


ENOTDIR 

EISDIR 

ENOMEM 
EROFS 


CONFORMS TO 


SVID, AT&T, POSIX, X/OPEN, BSD 4.3 


BUGS 


pathname points outside your accessible address space. 


W rite access to the directory containing pathname isnot allowed for the 
process's effective uid, or one of the directories in pathname did not allow search 
(execute) permission. 


The directory containing pathname has thesticky-bit (s_tsvtx) set and the 
process's effective uid is neither the uid of the file to be deleted nor that of the 
directory containing it. 

athname was too long. 

A directory component in pat hname does not exist or isa dangling symbolic 
ink. 

A component used asa directory in pat hname isnot, in fact, a directory. 
athname refers to a directory. 

Insufficient kernel memory was available. 

athname refersto afile on a read-only filesysten. 





Inadequacies in the protocol underlying N FS can cause the unexpected disappearance of files that are still being used. 


SEE ALSO 


unlink(2), rename(2), open(2), rmdir(2), mknod(2), mkfifo(3), link(2), rm(1), untink(8) 


Linux, 13 July1994 


res query,res search,res mkquery, res send, res init, 
dn_comp,dn_ expand 


res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand— Resolver routines 


SYNOPSIS 


#include <sys/types.h> 
#include <netinet/in.h> 


#include <arpa/nameser.h> 


#include <resolv. 


res _query(dname, class, 
const char *dname; 

int class, type; 
u_char *answer ; 

int anslen; 


h> 


type, 


answer, 


anslen) 


res query, res search, res mkquery, res send, res init, dn_ comp, dn_ expand 


res_search(dname, class, type, answer, anslen) 
const char *dname; 

int class, type; 

u char *answer ; 

int anslen; 


res mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen) 
int 0p; 

const char *dname; 

int class, type; 

const char *data; 

int datalen; 

struct rrec *newrr ; 

u_char *buf ; 

int buflen; 


res_send(msg, msglen, answer, ansl en) 
const u_char *msq; 

int msglen; 

u_char *answer ; 

int anslen; 


res_init() 


dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr) 
const char *exp_dn; 

u char *comp_dn; 

int length; 

u_char **dnptrs, **lastdnptr; 


dn_expand(msg, eomorig, comp_dn, exp_dn, length) 
const u_char *msg, *eomorig, *comp_dn; 

char *exp_dn; 

int length; 

hstrerror(int err); 


DESCRIPTION 
T hese routines are used for making, sending and interpreting query and reply messages with Internet domain name servers. 


Global configuration and state information that is used by the resolver routines is kept in the structure _res. M ost of the 
values have reasonable defaults and can be ignored. O ptions stored in _res.options are defined in resolv.h and areas 
follows. O ptions are stored as a simple bit mask containing the bitwise or of the options enabled. 


RES_INIT Trueif the initial nameserver address and default domain name are 
initialized (that is, res_init has bem called). 

RES_DEBUG Print debugging messages. 

RES_AAONLY Accept authoritative answers only. W ith this option, res_send should 


continue until it finds an authoritative answer or finds an error. 
Currently, this is not implemented. 


RES_USEVC Use TCP connections for queries instead of UDP datagrams. 

RES_STAYOPEN Used with res_useve to keep the TCP connection open between queries. 
This is useful only in programs that regularly do many queries. UD P 
should be the normal mode used. 

RES_IGNTC Unused currently (ignore truncation errors— don’t retry with TCP). 

RES_RECURSE Set the recursion-desired bit in queries. T his is the default. (res_send does 
not do iterative queries and expects the name server to handle recursion.) 
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RES_DEFNAMES If set, res_search will append the default domain name to single 
component names (those that do not contain adot). This option is 
enabled by default. 

RES_DNSRCH If this option is set, res_search will search for hostnames in the current 
domain and in parent domains; see hostname(7). T his is used by the 
standard host lookup routine gethostbyname(3). T his option is enabled 
by default. 

RES_NOALIASES This option turns off the user level aliasing feature controlled by the 
HOSTALIASES @nvironment variable. N etwork daemons should set this 
option. 


Theres_init routine reads the configuration file (if any; see resolver(5)) to get the default domain name, search list and the 
Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current 
domain name is defined by the hostname if not specified in the configuration file it can be overridden by the environment 
variable LocALDoMAIN. T his environment variable may contain several blank-separated tokens if you wish to override the 
search list on a per-process basis. Thisis similar to the search command in the configuration file Another environment 
variable (RES_OPTIONS) Can be set to override certain internal resolver options that are otherwise set by changing fidds in the 
_res structure or are inherited from the configuration file's options command. T he syntax of the Res_opTIons environment 
variable is explained in resolver(5). Initialization normally occurs on the first call to one of the other resolver routines. 


Theres_query function provides an interface to the server query mechanism. It constructs a query, sends it to the local 
server, awaits a response, and makes prdiminary checks on the reply. T he query requests information of the specified type 
and class for the specified fully-qualified domain name dname. The reply message is left in the answer buffer with length 
ansi en Supplied by the calle. 


The res_search routine makes a query and awaits a response like res_query, but in addition, it implements the default and 
search rules controlled by the RES_DEFNAMES and RES_DNSRCH options. It returns the first successful reply. 


Theremaining routines are lower-level routines used by res_query. T h@ res_mkquery function constructs a standard query 
message and places it in buf. It returns the size of the query, or -1 if the query is larger than buflen. The query type op is 
usually query, but can be any of the query types defined in <arpa/nameser .h>. The domain name for the query is given by 
dname. Newrr iS Currently unused but isintended for making update messages. 


The res_send routine sends a preformatted query and returns an answe’. It will call res_init if RES_INIT isnot set, send the 
query to the local nameserver, and handle time outs and retries. The length of the reply message is returned, or -1 if there 
were errors. 


The dn_comp function compresses the domain name exp_dn and storesit in comp_dn.T he Sze of the compressed nameis 
returned or -1 if there were errors. The size of the array pointed to by comp_dn is given by length. T he compression uses an 
array of pointers dnptrs to previously-compressed namesin the current message. The first pointer points to the beginning of 
the message and the list ends with nut. Thelimit to the array is specified by 1astdnptr. A side effect of dn_comp isto update 
the list of pointers for labels inserted into the message as the name is compressed. If dnptr iSNULL, Names are not compressed. 
If lastdnptr iSNULL, the list of labels is not updated. 


The dn_expand entry expands the compressed domain name comp_dn to a full domain name. T he compressed name is 
contained in a query or reoly message; msg is a pointer to the beginning of the message. The uncompressed name is placed in 
the buffer indicated by exp_dn, which is of size length. T hesize of compressed nameis returned or -1 if there was an error. 


FILES 


/etc/resolv.cont See resolver(5) 


SEE ALSO 
gethostbyname(3), named(8), resolver(5), hostname(7), 
RFC 1032, RFC 1033, RFC 1034, RFC1035, RFC974 
SM M: 11 Name Server O perations Guide for BIN D 
11 December 1995 


rewinddir 
rewinddir— Resets directory stream 
SYNOPSIS 


#include <sys/types.h> 
#include <dirent.h> 
void rewinddir(DIR *dir); 


DESCRIPTION 


The rewinddir() function resets the position of the directory stream dir to the beginning of the directory. 


RETURN VALUE 


The readdir() function returns no value. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3 


SEE ALSO 


opendir(3), readdir(3), closedir(3), seekdir(3), telldir(3), scandir(3) 
11 June1995 


rint 
rint— Rounds to closest integer 


SYNOPSIS 


#include <math.h> 
double rint(double x); 


DESCRIPTION 


Therint() function rounds« to an integer value according to the prevalent rounding mode. T he default rounding modeis 
to round to the nearest integer. 


RETURN VALUE 


The rint() function returns the integer value as a floating-point number. 


CONFORMS TO 


BSD 4.3 
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SEE ALSO 
abs(3), ceil(3), fabs(3), floor(3), 1abs(3) 
6 June1993 


rquota 


rquota— Implements quotas on remote machines 


SYNOPSIS 


/usr/include/rpcsvc/rquota.x 


DESCRIPTION 


The rquota( ) protocol inquires about quotas on remote machines. It is used in conjunction with N FS because N FS itself 
does not implement quotas. 


PROGRAMMING 
#include <rpcsvc/rquota.h> 
The following XDR routines are available in 1ibrpcsvc: xdr_getquota_arg: 


xdr_getquota_rslt 
xdr_rquota 


SEE ALSO 


quota(1), quotact1(2) 
6 October 1987 


scandir, alphasort 


scandir, alphasort— Scan a directory for matching entries 


SYNOPSIS 


#include <dirent.h> 

int scandir(const char *dir, struct dirent ***namelist, 

int (*select)(const struct dirent *), 

int (*compar )(const struct dirent **, const struct dirent **)); 
int alphasort(const struct dirent **a, const struct dirent **b); 


DESCRIPTION 


The scandir() function scans the directory dir, calling select() on each directory entry. Entries for which select() returns 
non-zero are stored in strings allocated via malloc(), sorted using qsort() with the comparison function compar(), and 
collected in array namelist that isallocated via malloc().If select iS NULL, all entries are selected. 


The alphasort() function can be used as the comparison function for the scandir() function to sort the directory entries into 
alphabetical order. Its parameters are the two directory entries, a and b, to compare 


RETURN VALUE 
The scandir() function returns the number of directory entries sdected or -1 if an error occurs. 


The alphasort() function returns an integer less than, equal to, or greater than zero if the first argument is considered to be 
respectively less than, equal to, or greater than the second. 


scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf 


ERRORS 
ENOMEM Insufficient memory to complete the operation 
CONFORMS TO 
BSD 4.3 
EXAMPLE 
/* print files in current directory in reverse order */ 
#include <dirent.h> 
main(){ 
struct dirent **namelist ; 
int n; 
n = scandir(".", &namelist, @, alphasort); 
if (n < 0) 
perror("scandir"); 
else 
while(n—) printf("%s\n", namelist [n]->d_name); 
} 
SEE ALSO 


opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), seekdir(3) 
GNU, 11 April 1996 


scant, fscanf, sscanf, vscanf, vsscanf, vfscant 








scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf— Input format conversion 
SYNOPSIS 

#include <stdio.h> 

int scanf( const char *format, ...); 

int fscanf( FILE *stream, const char *format, ...); 

int sscanf( const char *str, const char *format, ...); 

#include <stdarg.h> 


int vscanf( const char *format ,valist ap); 
int vsscanf( const char *str, const char *format ,va_ist ap); 
int vfscanf( FILE *stream, const char *format ,va_list ap); 


DESCRIPTION 


The scant family of functions scans input according to a format as described bdow. This format may contain conversion 
specifiers ; the results from such conversions, if any, are stored through the pointer arguments. The scant function reads 
input from the standard input stream stdin, fscanf reads input from the stream pointer stream, and sscanf reads its input 
from the character string pointed to by str. 


The vfscanf function is analogous to vfprintf(3) and reads input from the stream pointer stream using a variable argument 
ist of pointers (see stdarg(3)). T he vscan¢ function scans a variable argument list from the standard input and the vsscanf 
function scans it from a string; these are analogous to the vprintf and vsprintf functions respectivey. 


Each successive pointer argument must correspond properly with each successive conversion specifier. All conversions are 
introduced by the x (percent sign) character. The format string may also contain other characters. Whitespace (such as 
blanks, tabs, or newlines) in the format string match any amount of whitespace including none, in theinput. Everything else 
matches only itself. Scanning stops when an input character does not match such a format character. Scanning also stops 
when an input conversion cannot be made. 
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CONVERSIONS 


Following thes character introducing a conversion, there may be anumbe of flag characters, as follows: 


* 


q 


Suppresses assignment. T he conversion that follows occurs as usual, but no pointer is used; the result of 
the conversion is simply discarded. 

Indicates that the conversion will bes, malloc will be applied to the needed memory space for the string, 
and the pointer to it will be assigned to the char pointer variable, which does not have to be initialized 
before. T his flag does not exit in AN SI C. 

Indicates that the conversion will be one of dioux orn and the next pointer is a pointer to ashort int 
(rather than int). 

Indicates eather that the conversion will be one of dioux or n and thenext pointer isa pointer to a long 
int (rather than int), or that the conversion will be one of efg and the next pointer is a pointer to 
double (rather than float). Specifying two 1 flags is equivalent to the flag. 

Indicates that the conversion will be either efg and the next pointer is a pointer to 1ong double or the 
conversion will be dioux and the next pointer isa pointer to 1ong long. (N ote that 1ong long isnot an 
ANSI C type Any program using this will not be portable to all architectures). 

Equivalent to L. T his flag does not exist in AN SI C. 


+ 





In addition to these flags, there may be an optional maximum fidd width, expressed as a decimal integer, between thes and 
the conversion. If no width is given, a default of infinity is used (with one exception, below); otherwise at most this many 
characters are scanned in processing the conversion. Before conversion begins, most conversions skip whitespace; this 
whitespace is not counted against the fidd width. 


The following conversions are available: 


2 
© 


oO >a xX x 


ma 


M atchesa literal %. T hat is, %% in the format string matches a single input % character. No conversion is 
done, and assignment does not occur. 

M atches an optionally signed decimal integer; the next pointer must be a pointer to int. 

Equivalent to 1a; this exists only for backwards compatibility. 

M atches an optionally signed integer; the next pointer must be a pointer to int. The integer is read in 
base 16 if it begins with ox or ex, in base 8 if it begins with o, and in base 10 otherwise. O nly 
characters that correspond to the base are used. 

M atches an unsigned octal integer; the next pointer must be a pointer to unsigned int. 

M atches an unsigned decimal integer; the next pointer must be a pointer to unsigned int. 

M atches an unsigned hexadecimal integer; the next pointer must be a pointer to unsigned int. 
Equivalent to x. 

M atches an optionally signed floating-point number; the next pointer must be a pointer to float. 
Equivalent to f. 

Equivalent to f. 

Equivalent to f. 

M atches a sequence of nonwhitespace characters; the next pointer must bea pointer to char, and the 
array must be large enough to accept all the sequence and the terminating NUL character. The input 
string stops at whitespace or at the maximum fidd width, whichever occurs first. 

M atches a sequence of width count characters (default 1); the next pointer must bea pointer to char, 
and there must be nnough room for all the characters (no terminating nuL is added). The usual skip of 
leading whitespace is suppressed. T 0 skip whitespace first, use an explicit space in the format. 

M atches a nonempty sequence of characters from the specified set of accepted characters; the next 
pointer must bea pointer to char, and there must be nnough room for all the characters in the string, 
plus a terminating nut character. The usual skip of leading whitespace is suppressed. The string isto be 
made up of characters in (or not in) a particular set; the set is defined by the characters between the 
open bracket ; character and aclose bracket } character. T he set excludes those characters if the first 


seekdir 


character after the open bracket isa circumflex (*). To include a close bracket in the set, make it the 
first character after the open bracket or the circumflex; any other position will end the set. The hyphen 
character (-) is also special; when placed between two other characters, it adds all intervening 
characters to the set. To includea hyphen, make it the last character before the final close bracket. For 
instance, [*]@-9-] meansthe set “everything except close bracket, zero through nine, and hyphen.” 
The string ends with the appearance of a character not in (or, with a circumflex, in) the set or when 
the field width runs out. 


p M atches a pointer value (as printed by %p in printf(3); the next pointer must be a pointer to void. 

n N othing is expected; instead, the number of characters consumed thus far from the input is stored 
through the next pointer, which must bea pointer to int. This is not aconversion, although it can be 
suppressed with the « flag. 

RETURN VALUES 


T hese functions return the number of input items assigned, which can be fewer than provided for, or even zero, in the event 
of a matching failure. Zero indicates that, while there was input available, no conversions were assigned; typically, this is due 
to an invalid input character, such as an alphabetic character for a%a conversion. T he value cor is returned if an input failure 
occurs before any conversion such as an end-of-file occurs. If an error or end-of-file occurs after conversion has begun, the 
number of conversions which were successfully completed is returned. 


SEE ALSO 


strtol(3), strtoul(3), strtod(3), getc(3), printt(3) 


STANDARDS 
The functions fscanf, scanf, and sscant conform to AN SI C3.159-1989 (ANSI C). 
Theq flag isthe BSD 4.4 notation for long 1ong, while 11 or the usage of L in integer conversions isthe GN U notation. 
The Linux version of these functions is based on the GN U 1ibio library. Take a look at the info documentation of GNU 
libe (glibc-1.08) for a more concise description. 

BUGS 


All functions are fully AN SI C3.159-1989-conformant, but provide the additional flags q and a as wall as an additional 
behavior of thet and 1 flags. T he latter may be considered to be a bug, as it changes the behavior of flags defined in AN SI 
C3.159-1989. 


Some combinations of flags defined by AN SI C are not making sensein AN SI C (for example sia). While they may havea 
well-defined behavior on Linux, this need not to be so on other architectures. T herefore, it usually is better to use flags that 
are not defined by AN SI C at all, thatis, use g instead of L in combination with diouxx conversionsor 11. 


The usage of q isnot the same ason BSD 4.4, as it may be used in float conversions equivalently to L. 
Linux man page 1 November 1995 


seekdir 
seekdir— Sets the position of the next readdir() call in the directory stream. 
SYNOPSIS 


#include <dirent.h> 
void seekdir(DIR *dir ,off_t offset); 


DESCRIPTION 


The seekdir() function sets the location in the directory stream from which thenext readdir() call will start. seekdir() 
should be used with an offset returned by telldir(). 
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RETURN VALUE 


The seekdir() function returns no value 


CONFORMS TO 
BSD 4,3 


SEE ALSO 


lseek(2), opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), scandir(3) 
31 March 1993 


setbuf, setbuffer, setlinebuf, setvbuf 


setbuf, setbuffer, setlinebuf, setvbuf— Stream buffering operations 


SYNOPSIS 


#include <stdio.h> 


int setbuf( FILE *stream, char *buf ); 

int setbuffer( FILE *stream, char *buf, size tsize); 

int setlinebuf( FILE *stream); 

int setvbuf( FILE *stream, char *buf,intmode , size_t size); 


DESCRIPTION 


The three types of buffering available are unbuffered, block buffered, and line buffered. W hen an output stream is unbuf- 
fered, information appears on the destination file or taminal as soon as written; when it is block buffered, many characters 
are saved up and written asa block; when it is line buffered, characters are saved up until anewlineis output or input is read 
from any stream attached to a terminal device (typically stdin). Thefunction tf1ush(3) may be used to force the block out 
early. (See fclose(3).) N ormally all files are block buffered. W hen the first I/O operation occurs on afile, mal1oc(3) is called, 
and a buffer is obtained. If a stream refers to a terminal (as stdout normally does), it is line buffered. T he standard error 
stream stderr is always unbuffered. 


The setvbuf function may be used at any time on any open stream to changeits buffer. The mode parameter must be one of 
the following three macros: 


_IONBF Unbuffered 
_IOLBF Line buffered 
_IOFBF Fully buffered 


Except for unbuffered files, thebuf argument should point to a buffer at least size bytes long; this buffer will be used instead 
of the current buffer. If the argument buf is NULL, only the modeis affected; a new buffer will be allocated on the next read or 
write operation. T he setvbut function may be used at any time, but can only change the mode of a stream when it is not 
“active”; that is, before any I/O, or immediately after a call to ff1ush. 

The other three calls are, in effect, simply aliases for calls to setvbuf. The setbut function is exactly equivalent to the call: 
setvbuf (stream, buf, buf ?_IOFBF :_IONBF, BUFSIZ); 

The setbutfer function isthe same, except that the size of the buffer isup to the caller, rather than being determined by the 
default Bursiz. The setlinebut function is exactly equivalent to the call: 

setvbuf(stream, (char *)NULL, IOLBF, 0); 
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SEE ALSO 


fopen(3), fclose(3), fread(3), malloc(3), puts(3), printf(3) 


STANDARDS 
The setbuf and setvbut functions conform to AN SI C3.159-1989 (ANSI C). 


BUGS 


The setbutfer and setlinebuf functions are not portable to versions of BSD before 4.2BSD, and may not be available under 
Linux. On 4.2BSD and 4.3BSD systems, setbut always uses a suboptimal buffer size and should be avoided. You must make 
sure that both buf and the space it points to still exist by the time stream is closed, which also happens at program termina- 
tion. For example, the following is illegal: 


#include <stdio.h> 

int main() 

{ 
char buf[BUFSIZ]; 
setbuf(stdin, buf); 
printf("Hello, world!\n"); 
return 0; 


BSD man page 29 N ovenber 1993 


setenv 


setenv— Changes or adds an environment variable 


SYNOPSIS 


#include <stdlib.h> 
int setenv(const char *name, const char *value,int overwrite); 
void unsetenv(const char *name); 


DESCRIPTION 


The setenv() function adds the variable name to the environment with the value value, if name does not already exist. If name 
does exist in the environment, then its value is changed to value if overwrite is non-zero; if overwrite is zero, then the value 
Of name isnot changed. 


Theunsetenv() function deletes the variable name from the environment. 


RETURN VALUE 


The setenv() function returns zero on success, or -1 if there was insufficient spacein the environment. 


CONFORMS T0 
BSD 4.3 


SEE ALSO 
getenv(3), putenv(3) 
BSD, 4 April 1993 
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set jmp 
setjmp— Saves stack context for nonlocal goto 


SYNOPSIS 


#include <setjmp.h> 
int setjmp(jmp_buf env ); 


DESCRIPTION 


set jmp and longjmp(3) are useful for dealing with errors and interrupts encountered in alow-leve subroutine of a program. 
set jmp() saves the stack context/environment in env for later use by longjmp(). T he stack context will be invalidated if the 
function which called setjmp() returns, 


RETURN VALUE 


It returns the value o if returning directly and non-zero when returning from 1ongjmp() using the saved context. 


CONFORMS TO 
POSIX 


NOTES 


POSIX does not specify if the signal context will be saved or not. If you want to save signal masks, use sigsetjmp(3). set jmp() 
makes programs hard to understand and maintain. If possible an alternative should be used. 


SEE ALSO 


longjmp(3), sigsetjmp(2), siglongjmp(2) 
25 November 1994 


setlocale 


setlocale— Sets the current locale 


SYNOPSIS 


#include <locale.h> 
char *setlocale(int category, const char * locale); 


DESCRIPTION 


The setlocale() function is used to set or query the program’s current locale Ifiocale isC or POSIX, the current locale is 
set to the portable locale 


If locale iS"", the locale is set to the default locale that is sdected from the environment variable LANG. 
On startup of the main program, the portable locale is selected as default. 
The argument cat egory determines which functions are influenced by the new locale: 


LC_ALL For all of the locale 

LC_COLLATE For the functions strcoll() and strxfrm(). 

LC_CTYPE For the character classification and conversion routines. 

LC_MONETARY For localeconv(). 

LC_NUMERIC For the decimal character. 

LC_TIME For strftime(). NULL if the request can not be honored. This string may be 


allocated in static storage. 


d gemptyset, sigfillset, sigaddset, i gdelset, sigismember 


A program may be made portable to all locales by calling setlocale(Lc_ALL, """""") after program initialization, by using the 
values returned from a localeconv() Call for locale dependent information and by using strcoll() or strxfrm() to compare 
strings. 

CONFORMS TO 
ANSI C, POSIX.1 
Linux supports the portable locales C and POSIX and also the European Latin-1 and Russian locales. 
The printt() family of functions may or may not honor the current locale 


SEE ALSO 


locale(1), localedet(1), strco11(3), isalpha(3), localeconv(3), strftime(3), locale(7) 
GNU, 18 April 1993 


siginterrupt 
siginterrupt— Allows signals to interrupt system calls 
SYNOPSIS 


#include <signal.h> 
int siginterrupt(int sig,int flag); 


DESCRIPTION 


The siginterrupt() function changes the restart behavior when a system call is interrupted by the signal sig.If the flag 
argument is false (@), then systems calls will be restarted if interrupted by the specified signal sig. T his is the default behavior 
in Linux. H owever, when anew signal handler is specified with the signa1(2) function, the system call is interrupted by 
default. 


If the flag argument is true (1) and no data has been transferred, then a system call interrupted by the signal sig will return 
-1 and the global variableerrno will be set to EINTR. 


If the f1ag argument is true (1) and data transfer has started, then thesystem call will be interrupted and will return the 
actual amount of data transferred. 


RETURN VALUE 


The siginterrupt() function returns on success, or -1 if the signal number sig isinvalid. 


ERRORS 


EINVAL The specified signal number isinvalid. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 
signal(2) 
13 April 1993 


Sigemptyset, sigfillset, sigaddset, sigdelset, sigismember 


sigemptyset, sigfillset, sigaddset, sigdelset, sigismember— PO SIX signal set operations 


Part III: Library Functions 


SYNOPSIS 


#include <signal.h> 

int sigemptyset(sigset_t *set); 

int sigfillset(sigset_t *set); 

int sigaddset(sigset_t *set ,int signum); 

int sigdelset(sigset_t *set ,int signum); 

int sigismember(const sigset_t *set,int signum); 


DESCRIPTION 


The sigsetops(3) functions allow the manipulation of POSIX signal sets. 
sigemptyset initializes the signal set given by set to empty, with all signals excluded from the set. 
sigfillset initializesset to full, including all signals. 
sigaddset and sigdelset add and delete, respectively, signal si gnum from set. 
sigismember tests whether si gnumiSamembe of set. 
RETURN VALUES 
sigemptyset, sigfullset, sigaddset, and sigdelset return @ On Success and -1 On error. 
sigismember returns 1 if signum isa member of set, 0 if signum isnot a member, and -1 on error. 


ERRORS 


EINVAL sig isnot a valid signal. 


CONFORMS TO 
POSIX 


SEE ALSO 


sigaction(2), sigpending(2), sigorocmask(2), sigsuspend(2) 
Linux 1.0, 24 Seotember 1994 


$n 
sin— Sine function 


SYNOPSIS 


#include <math.h> 
double sin(double x); 


DESCRIPTION 


The sin) function returns the sine of x, where x is given in radians. 


RETURN VALUE 


Thesin() function returns a value between -1 and 1. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3,1SO 9899 


oe (an 


8 June1993 


SEE ALSO 
acos(3), asin(3), atan(3), atan2(3), cos(3), tan(3) 


sinh 
sinh— H yperbolic sine function 


SYNOPSIS 


#include <math.h> 
double sinh(double x); 


DESCRIPTION 


The sinh) function returns the hyperbolic sine of x, which is defined mathematically as [exp(x)- exp(-x)] / 2. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


acosh(3), asinh(3), atanh(3), cosh(3), tann(3) 
13 June1993 


Sleep 


sleep— Sleeps for the specified number of seconds 


SYNOPSIS 


#include <unistd.h> 
unsigned int sleep(unsigned int seconds); 


DESCRIPTION 


sleep() makes the current process sleep until seconds seconds have elapsed or a signal arrives that is not ignored. 


RETURN VALUE 


Thereturn value is zero if the requested time has dapsed, or the number of seconds left to sleep. 


CONFORMS TO 
POSIX.1 


BUGS 
sleep()may beimplemented using s1GaLrm; mixing calls to alarm() and sleep() isa bad idea. 
Using longjmp() from asignal handler or modifying the handling of stcacrm while sleeping will cause undefined results. 


SEE ALSO 


signal(2), alarm(2) 
GNU, 7 April 1993 
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snprintf, vsnprintt 


snprintf, vsnprintf— Formatted output conversion 


SYNOPSIS 


#include <stdio.h> 


int snprintf ( char *str, size_t n, 
const char *format, ... ); 


#include <stdarg.h> 


int vsnprintf ( char *str, size_t on, 
const char *format, va_list ap ); 


DESCRIPTION 
snprintf writes output to thestringstr, under control of theformat string that specifies how subsequent arguments are 
converted for output. It is similar to sprintf(3), except that n specifies the maximum number of characters to produce. 
The trailing null character is counted towards this limit, so you should allocate at least n characters for the string str. 





vsnprintf isthe equivalent of snprintf with the variable argument list specified directly as for vprintf. 


RETURN VALUE 


The return value is the number of characters stored, not including the terminating null. If this value equalsn, then there was 
not enough space in str for all the output. You should try again with a bigger output string. 


EXAMPLE 
H ereisasample program that dynamically enlarges its output buffer: 


/* Construct a message describing the value of a 
variable whose name is NAME and whose value is 
VALUE. */ 

char * 

make_message (char *name, char *value) 

{ 

/* Guess we need no more than 100 chars of space. */ 
int size = 100; 
char *buffer = (char *) xmalloc (size); 
while (1) 
{ 
/* Try to print in the allocated space. */ 
int nchars = snprintf (buffer, size, 
"value of %s is %S", name, value); 
/* If that worked, return the string. */ 
if (nchars < size) 
return buffer; 

/* Else try again with twice as much space. */ 

size *= 2; 

buffer = (char *) xrealloc (size, buffer) 


} 
CONFORMS TO 


These areGN U extensions. 


gdarg 


GNU, 16 Seotenber 1995 


SEE ALSO 


printf(3), sprintf(3), vsprintf(3), stdarg(3) 


sqrt 
sqrt— Square root function 


SYNOPSIS 


#include <math.h> 
double sqrt(double x); 


DESCRIPTION 


The sqrt() function returns the non-negative square root of x. It fails and sets errno to EDom, if x is negative. 


ERRORS 


EDOM x iS negative. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
hypot(3) 
21 June1993 


stdarg 


stdarg— Variable argument lists 


SYNOPSIS 


#include <stdarg.h> 

void va_start( va_list ap, last); 
type va_arg( va_list ap, type); 
void va_end( va_list ap); 


DESCRIPTION 


A function may be called with a varying number of arguments of varying types. T heinclude file stdarg.h declares a type 
va_list and defines three macros for stepping through a list of arguments whose number and types are not known to the 
called function. 


The called function must declare an object of type va_list that is used by the macros va_start, va_arg, and va_end. 
The va_start macro initializes ap for subsequent use by va_arg and va_end, and must be called first. 


The parameter | ast isthename of thelast parameter before the variable argument list; that is, the last parameter of which 
the calling function knows the type. 


Because the address of this parameter is used in the va_start macro, it should not be declared as a register variable, a 
function, or an array type 


Theva_start macro returns no value. 
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The va_arg macro expands to an expression that has the type and value of the next argument in the call. The parameter ap is 
the va_list ap initialized by va_start. Each call to va_arg modifiesap so that the next call returnsthenext argument. The 
parameter type is a type name specified so that the type of a pointer to an object that has the specified type can be obtained 
simply by adding a * to type. 


If thereis no next argument, or if type isnot compatible with the type of the actual next argument (as promoted according 
to the default argument promotions), random errors will occur. 


The first use of the va_arg macro after that of the va_start macro returns the argument after last. Successive invocations 
return the values of the remaining arguments. 


The va_end macro handles anormal return from the function whose variable argument list was initialized by va_start. 
The va_end macro returns no value 


EXAMPLE 


The function foo takes a string of format characters and prints out the argument associated with each format character based 
on the type 


void foo(char *fmt, ...) 
{ 

va_list ap; 

int d; 

char c, *p, *s; 


va_start(ap, fmt); 
while (*fmt) 
switch(*fmt++) { 
case 's': /* string */ 
s = va_arg(ap, char *); 
printf("string %s\n", s); 
break; 
case ‘d': f* int, */ 
d = va_arg(ap, int); 
printf("int %d\n", d); 
break; 
case 'c': /* char */ 
c = va_arg(ap, char); 
printf("char %c\n", c); 
break; 





} 
va_end(ap); 


STANDARDS 
Theva_start, va_arg, and va_end macros conform to AN SI C3,.159-1989 (ANSI C). 


COMPATIBILITY 


T hese macros are not compatible with the historic macros they replace A backwards-compatible version can be found in the 
include file varargs.h. 


BUGS 


Unlike the varargs macros, the stdarg macros do not permit programmers to codea function with no fixed arguments. T his 
problem generates work mainly when converting varargs code to stdarg code, but it also creates difficulties for variadic 
functions that wish to pass all of their arguments on to a function that takes a va_list argument, such as vfprint#(3). 
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¢dio 


Std10 


stdio— Standard input/output library functions 


SYNOPSIS 
#include <stdio.h> 
FILE *stdin; 
FILE *stdout; 
FILE *stderr; 


DESCRIPTION 


The standard I/O library provides asimple and efficient buffered stream |/O interface. Input and output is mapped into 
logical data streams and the physical I/O characteristics are concealed. The functions and macros are listed in this section; 
more information is available from the individual man pages. 


A stream is associated with an external file (which may be a physical device) by opening a file, which may involve creating a 
new file Creating an existing file causes its former contents to be discarded. If a file can support positioning requests (such as 
a disk file as opposed to aterminal), then afile position indicator associated with the stream is positioned at the start of the 
file (byte zero), unless the file is opened with append mode. If append mode is used, the position indicator will be placed the 
end-of-file. The position indicator is maintained by subsequent reads, writes, and positioning requests. All input occurs as if 
the characters were read by successive calls to the fgetc(3) function; all output takes place as if all characters were read by 
successive calls to the fputc(3) function. 


A file is disassociated from a stream by closing the file. O utput streams are flushed (any unwritten buffer contents are 
transferred to the host environment) before the stream is disassociated from the file The value of a pointer to aFILe object is 
indeterminate after a file is closed (garbage). 


A file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it 
can be repositioned at the start). If the main function returns to its original caller, or the exit(3) function is called, all open 
files are closed (hence all output streams are flushed) before program termination. O ther methods of program termination, 
such as abort(3) do not bother about closing files properly. 


At program startup, three text streams are predefined and need not be opened explicitly: standard input (for reading 
conventional input), standard output (for writing conventional input), and standard error (for writing diagnostic output). 
T hese streams are abbreviated stdin, stdout, and stderr. When opened, the standard error stream is not fully buffered; the 
standard input and output streams are fully buffered if and only if the streams do not to refer to an interactive device. 


Output streams that refer to terminal devices are always line buffered by default; pending output to such streamsis written 
automatically whenever an input stream that refers to a terminal device is read. In cases where a large amount of computation 
is done after printing part of aline on an output terminal, it is necessary to ff1ush(3) the standard output before going off 
and computing so that the output will appear. 


The stdio library is a part of the library 1ibc and routines are automatically loaded as needed by the compilers cc(1) and 
pc(1). The synopsts sections of the following manual pages indicate which include files are to be used, what the compiler 
declaration for the function looks like, and which external variables are of interest. 

The following are defined as macros; these names may not be reused without first removing thar current definitions with 
#undef: BUFSIZ, EOF, FILENAME_MAX, FOPEN_MAX, L_cuserid, L_ctermid, L_tmpnam, NULL, SEEK_END, SEEK_SET, SEE_CUR, TMP_MAX, 
clearerr, feof, ferror, fileno, fropen, fwopen, getc, getchar, putc, putchar, stderr, stdin, stdout. Function versions of the 
macro functions feof, ferror, clearerr, fileno, getc, getchar, putc, and putchar exist and will be used if the macros 
definitions are explicitly removed. 


SEE ALSO 


open(2), close(2), read(2), write(2) 


Part III: Library Functions 


BUGS 


The standard buffered functions do not interact wel with certain other library and system functions, especially vfork and 
abort. T his may not be the case under Linux. 








STANDARDS 
The stdio library conforms to AN SI C3.159-1989 (AN SI C). 
LIST OF FUNCTIONS 
Function D esrription 
clearerr Check and reset stream status 
close Close a stream 
dopen Stream open functions 
eof Check and reset stream status 
error Check and reset stream status 
flush Flush a stream 
getc Get next character or word from input stream 
getline Get alinefrom a stream 
getpos Reposition a stream 
gets Get alinefrom a stream 
ileno Check and reset stream status 
open Stream open functions 
printf Formatted output conversion 
purge Flush a stream 
putc Output acharacter or word to a stream 
puts Output aline to astream 
read Binary stream input/output 
reopen Stream open functions 
ropen Ope a stream 
scant Input format conversion 
seek Reposition a stream 
setpos Reposition a stream 
tell Reposition a stream 
write Binary stream input/output 
getc Get next character or word from input stream 
getchar Get next character or word from input stream 
gets Get alinefrom a stream 
getw Get next character or word from input stream 
mktemp M ake temporary filename (unique) 
perror System error messages 
printf Formatted output conversion 
pute Output acharacter or word to a stream 
putchar Output acharacter or word to a stream 
puts Output aline to astream 


putw Output acharacter or word to a stream 


remove Remove directory entry 
rewind Reposition a stream 

scanf Input format conversion 
setbuf Stream buffering operations 
setbuffer Stream buffering operations 
setlinebuf Stream buffering operations 
setvbuf Stream buffering operations 
sprintf Formatted output conversion 
sscanf Input format conversion 
strerror System error messages 
sys_errlist System error messages 
sys_nerr System error messages 
tempnam Temporary file routines 
tmpfile Temporary file routines 
tmpnam Temporary file routines 
ungetc Un-get character from input stream 
vfprintf Formatted output conversion 
vfscanf Input format conversion 
vprintf Formatted output conversion 
vscanf Input format conversion 
vsprintt Formatted output conversion 
vsscanf Input format conversion 
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stpcpy 


stpcpy— Copies a string returning a pointer to its end 


SYNOPSIS 


#include <string.h> 
char *stpcpy(char *dest, const char *src); 


DESCRIPTION 


The stpepy() function copies the string pointed to by src (including the terminating \o character) to the array pointed to by 
dest. T he strings may not overlap, and the destination stringdest must be large enough to receive the copy. 


RETURN VALUE 
stpepy() returnsa pointer to the end of the string dest (that is, the address of the terminating null character) rather than the 
beginning. 
EXAMPLE 
For example, this program uses stpcpy to concatenate foo and bar to produce foobar, which it then prints: 
#include <string.h> 
int 
main (void) 


{ 


Part III: Library Functions 


char *to = buffer; 

to = stpcpy (to, "foo"); 
to = stpcpy (to, "bar"); 
printf ("%s\n", buffer); 


CONFORMS TO 
This function is not part of the AN SI or PO SIX standards, and is not customary on UNIX systems, but isnotaGNU 


invention ather. Perhapsit comes from MS-DOS. 
SEE ALSO 


strepy(3), bcopy(3), memccpy(3), memcpy(3), memmove(3) 
GNU, 3 Septenber 1995 


strcasecmp, strncasecmp 


strcasecmp, strncasecmp— C ompare two strings, ignoring case 


SYNOPSIS 


#include <string.h> 
int strcasecmp(const char *sl, const char *s2); 
int strncasecmp(const char *sl, const char *s2, size_t n); 


DESCRIPTION 


The strcasecmp() function compares the two strings s1 and s2, ignoring the case of the characters. It returns an integer less 
than, equal to, or greater than zero ifs1 isfound, respectively, to be less than, to match, or be greater than s2. 


The strncasecmp() function is smilar, except it only compares the first n characters of s1. 


RETURN VALUE 


The strcasecmp() and strncasecmp() functions return an integer less than, equal to, or greater than zero if si (or the first n 
bytes thereof ) is found, respectively, to be less than, to match, or be greater than s2. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 


bemp(3), memcmp(3), stremp(3), strco11(3), strncmp(3) 
11 April 1993 


strcat, strncat 


strcat, strncat— C oncatenate two strings 


SYNOPSIS 


#include <string.h> 
char *strcat(char *dest, const char *src); 
char *strncat(char *dest, const char *src, size_t n); 


gtrcomp, trncmp 
DESCRIPTION 


The strcat() function appends thesrc string to thedest string, overwriting the \o character at the end of dest, and thn 
adds a terminating \o character. The strings may not overlap, and thedest string must have enough space for the result. 


The strncat() function is similar, except that only the first n characters of src are appended to dest. 


RETURN VALUE 


The strcat() and strncat() functions return a pointer to the resulting string dest. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


beopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 
GNU, 11 April 1993 


strchr, strrchr 


strchr, strrchr— Locate character in string 


SYNOPSIS 


#include <string.h> 
char *strchr(const char *s,int c); 
char *strrchr(const char *s ,int c); 


DESCRIPTION 
The strchr() function returns a pointer to the first occurrence of the characte c in the strings. 
The strrchr() function returns a pointer to the last occurrence of the character « in the strings. 


RETURN VALUE 


The strchr() and strrehr() functions return a pointer to the matched character or nuLt if the character is not found. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


index(3), memchr(3), rindex(3), strpbrk(3), strsep(3), strspn(3), strstr(3), strtok(3) 
12 April 1993 


strcmp, strncmp 


stremp, strncmp— C ompare two strings 


SYNOPSIS 


#include <string.h> 
int strcmp(const char *s1, const char *s2); 
int strncmp(const char *s1, const char *s2, size_t n); 


Part III: Library Functions 


DESCRIPTION 


The stremp() function compares the two stringss1 and s2.It returns an integer less than, equal to, or greater than zero if s1 
is found, respectively, to be less than, to match, or be greater than s2. 


The strnemp() function issimilar, except it only compares the first n characters of s1. 


RETURN VALUE 


The stremp() and strnemp() functions return an integer less than, equal to, or greater than zero if s1 (or thefirst n bytes 
thereof ) is found, respectively, to be less than, to match, or be greater than s2. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


bemp(3), memcmp(3), strcasecmp(3), strncasecmp(3), strcol1(3) 
11 April 1993 


strcoll 


strcoll— Compares two strings using the current locale 


SYNOPSIS 


#include <string.h> 
int strcoll(const char *s1, const char *s2); 


DESCRIPTION 


The strco11() function compares the two stringss1 and s2. It returns an integer less than, equal to, or greater than zero if s1 
is found, respectively, to be less than, to match, or be greater than s2. The comparison is based on strings interpreted as 
appropriate for the program’s current locale for category Lc_COLLATE. (S€@ setlocale(3)). 


RETURN VALUE 


The strco11() function returns an integer less than, equal to, or greater than zero ifs1 is found, respectively, to be less than, 
to match, or be greater than s2, when both are interpreted as appropriate for the current locale 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


NOTES 
The Linux C Library currently hasn't implenented the complete PO SI X-collating. 
In the POSIX or C locales, strco11() is equivalent to stremp(). 


SEE ALSO 


bemp(3), memcmp(3), strcasecmp(3), stremp(3), strxfrm(3), setlocale(3) 
GNU, 12 April 1993 


strcpy, strncpy 


strepy, strncpy— Copy astring 


grdup 


SYNOPSIS 


#include <string.h> 
char *strcpy(char *dest, const char *src); 
char *strncpy(char *dest, const char *src, size_t n); 


DESCRIPTION 


The strepy() function copies the string pointed to besrc (including the terminating \o character) to the array pointed to by 
dest. T he strings may not overlap, and the destination stringdest must be large enough to receive the copy. 


The strnepy() function is similar, except that not more than n bytes of src are copied. T hus, if there is no null byte among 
the first n bytes of src, the result will not be null-terminated. 


In the case where the length of src isless than that ofn, the remainder of dest will be padded with nulls. 


RETURN VALUE 


The strepy() and strncpy() functions return a pointer to the destination string dest. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, ISO 9899 


SEE ALSO 


bcopy(3), memecpy(3), memcpy(3), memmove(3) 
GNU, 11 April 1993 


strdup 


strdup— D uplicates a string 


SYNOPSIS 


#include <string.h> 
char *strdup(const char *s); 


DESCRIPTION 


The strdup() function returns a pointer to anew string that is a duplicate of the strings. M emory for the new string is 
obtained with malloc(3), and can be freed with free(3). 


RETURN VALUE 


The strdup() function returns a pointer to the duplicated string, or nuLt if insufficient memory was available. 


ERRORS 


ENOMEM Insufficient memory available to allocate duplicate string 


CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 
calloc(3), malloc(3), realloc(3), free(3) 
GNU, 12 April 1993 
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strerror 


strerror— Returns string describing error code 
SYNOPSIS 

#include <string.h> 

char *strerror(int errnum); 


DESCRIPTION 


The strerror() function returns a string describing the error code passed in the argument err num. The string can only be 
used until the next call to strerror(). 


RETURN VALUE 


The strerror() function returns the appropriate description string, or an unknown error message if the error codeis 
unknown. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


errno(3), perror(3), strsignal(3) 
GNU, 13 April 1993 


strfry 


strfry— Randomizes a string 


SYNOPSIS 


#include <string.h> 
char *strfry(char *string); 


DESCRIPTION 


The strfry() function randomizes the contents of st ring by using rand(3) to randomly swap characters in the string. The 
result is an anagram of st ring. 


RETURN VALUE 


The strfry() function returns a pointer to the randomized string. 


CONFORMS TO 
The strfry() function is unique to the Linux C Library and GNU C Library. 


SEE ALSO 


memfrob(3) 
GNU, 12 April 1993 


strftime 


strftime— Formats date and time 


SYNOPSIS 


#include <time.h> 


size t strftime(char *s, size_t max, const char *format, 


const struct tm *tm); 


DESCRIPTION 


The strftime() function formats the broken-down timet m according to the format specification format and places the result 
in the character array s of size max. 


drftime 


Ordinary characters placed in the format string are copied to s without conversion. Conversion specifiers are introduced by a 
% Character, and are replaced ins as follows: 


290 
66 


The broken-down time structure tm is defined in <time.h> as follows: 


struct 


{ 
int 
int 
int 
int 
int 
int 
int 
int 
int 
}; 





aS SS SSS SS 


© 


%A 
Sb 
%B The full month nameaccording to the current locale 
%C 
%d 
oH 
%1 
%j 
6m The month as a decimal number (range 01 to 12) 
eM The minute as a decimal number 
sp 
locale 
%S The second as a decimal number 
%U 
day of the first week 
oa 
day of the first week 
So The day of the week as a decimal, Sunday being 0 
6x 
%X 
sy 
%Y The year as a decimal number including the century 
%Z The time zoneor name or abbreviation 


A literal » character 


tm 


sec; /* seconds */ 

min; /* minutes */ 

hour; /* hours */ 

mday; /* day of the month */ 

mon; /* month */ 

year; /* year */ 

wday; /* day of the week */ 

yday; /* day in the year */ 
isdst; /* daylight saving time */ 


The abbreviated weekday name according to the current locale 
The full weekday name according to the current locale 
The abbreviated month name according to the current locale 


The preferred date and time representation for the current locale 

The day of the month as a decimal number (range 01 to 31) 
Thehour as a decimal number using a 24-hour clock (range 00 to 23) 
Thehour as a decimal number using a 12-hour clock (range 01 to 12) 
The day of the year as a decimal number (range 001 to 366) 


The preferred date representation for the current locale without the time 
The preferred time representation for the current locale without the date 
The year as a decimal number without a century (range 00 to 99) 


Either am. or p.m. according to the given time value, or the corresponding strings for the current 


The week number of the current year as a decimal numbe,, starting with the first Sunday as the first 


The week number of the current year as a decimal numbe,, starting with the first M onday as the first 
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Themembers of the tm structure are 


m_sec The number of seconds after the minute, normally in the range 0 to 59, but can be up to 
61 to allow for leap seconds. 

m_min Thenumber of minutes after the hour, in the range 0 to 59. 

m_hour The number of hours past midnight, in the range 0 to 23. 

m_mday The day of the month, in the range 1 to 31. 

m_mon The number of months since] anuary, in the range 0 to 11. 

m_year The number of years since 1900. 

m_wday The number of days since Sunday, in the range 0 to 6. 

m_yday Thenumber of days since] anuary 1, in the range 0 to 365. 

m_isdst A flag that indicates whether daylight saving timeis in effect at the time described. The 





value is positive if daylight saving time isin effect, zero if it isnot, and negative if the 
information is not available 


RETURN VALUE 


The strttime() function returns the number of characters placed in the array s, not including the terminating nuLt character. 
If the value equals max, it means that the array was too small. 


CONFORMS TO 

SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 

date(1), time(2), ctime(3), setlocale(3), sprintf(3) 
NOTES 


The function supports only those locales specified in 1ocale(7) 
GNU, 2 July1993 


strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, 
strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, 
strpbrk, strrchr, strsep, strspn, strstr, strtok, strxfrm, 
index, rindex 


strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, 
strpbrk, strrchr, strsep, strspn, strstr, strtok, strxfrm, index, rindex— String operations 


SYNOPSIS 


#include <string.h> 

int strcasecmp(const char *sl, const char *s2); 
char *strcat(char *dest, const char *src); 

char *strchr(const char *s,int c); 

int strcmp(const char *s1, const char *s2); 

int strcoll(const char *s1, const char *s2); 

char *strcpy(char *dest, const char *src); 

size_t strcspn(const char *s, const char *reject ); 
char *strdup(const char *s); 


grpbrk 


char *strfry(char *string); 

size_t strlen(const char *s); 

char *strncat(char *dest, const char *src, size_t n); 
int strncmp(const char *s1, const char *s2, size_t n); 
char *strncpy(char *dest, const char *src, size_t n); 
int strncasecmp(const char *sl, const char *s2, size_t n); 
char *strpbrk(const char *s, const char *accept ); 

char *strrchr(const char *s ,int c); 

char *strsep(char **stringp, const char *delim); 

size_t strspn(const char *s, const char *accept ); 

char *strstr(const char *haystack, const char *needle); 
char *strtok(char *s, const char *delim); 

size_t strxfrm(char *dest, const char *src, size_t n); 
char *index (constchar*"s,int c); 

char *rindex(const char *s ,int c); 


DESCRIPTION 


The string functions perform string operations on nuLL-terminated strings. See the individual man pages for descriptions of 
each function. 


SEE ALSO 


index(3), rindex(3), strcasecmp(3), strcat(3), strchr(3), stremp(3), strcol1(3), strcpy(3), strespn(3), strdup(3), strfry(3), 
strlen(3), strncat(3), strncmp(3), strncpy(3), strncasecmp(3), strpprk(3), strrchr(3), strsep(3), strspn(3), strstr(3), 
strtok(3), strxfrm(3) 


9 April 1993 


strlen 


strlen— Calculates the length of astring 


SYNOPSIS 


#include <string.h> 
size_t strlen(const char *s); 


DESCRIPTION 


The strien() function calculates the length of the strings, not including the taminating \o character. 


RETURN VALUE 


Thestrien() function returns the number of characters ins. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3,1SO 9899 


SEE ALSO 


string(3) 
12 April 1993 


strpbrk 


strpbrk— Searches a string for any of a set of characters 


Part III: Library Functions 


SYNOPSIS 


#include <string.h> 
char *strpbrk(const char *s, const char *accept ); 


DESCRIPTION 


The strpbrk() function locates the first occurrence in the strings of any of the characters in the stringaccept. 


RETURN VALUE 


The strpprk() function returns a pointer to the character in s that matches one of the charactersin accept. 


CONFORMS TO 
SVID 3, POSIX, BSD 4.3,1SO 9899 


SEE ALSO 


index(3), memchr(3), rindex(3), strchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 
12 April 1993 


strptime 


strptime— Converts astring representation of time to a time tm structure 


SYNOPSIS 


#include <time.h> 
char *strptime(char *buf, const char *format , const struct tm *tm) 


DESCRIPTION 


strptime() isthe complementary function to strftime() and converts the characte string pointed to by buf to a time value, 
which is stored in the tm structure pointed to byt m, using the format specified by format. format is acharacter string that 
consists of fidd descriptors and text characters, reminiscent of scanf(3). Each field descriptor consists of a character 
followed by another character that specifies the replacenent for the fidd descriptor. All other characters are copied from 
format into the result. T he following field descriptors are supported: 


%5% Same as %. 

%a, %A D ay of week, using locale’s weekday names; either the abbreviated or full name may be 
specified. 

%b, %B, %h M onth, using locale’s month names; either the abbreviated or full name may be 
specified. 


D ate and time as %x, %x. 


ro} 


%C D ate and time, in locale’s long-format date and time representation. 
%d, %@ D ay of month (1-31; leading zeroes are permitted but not required). 
%D D ate as %m/sd /%y. 

%H, Sk H our (0-23; leading zeroes are permitted but not required). 

%I, %1 H our (0-12; leading zeroes are permitted but not required). 

%j D ay number of year (001-366). 

Sm M onth number (1-12; leading zeroes are permitted but not required). 
ca M inute (0-59; leading zeroes are permitted but not required). 

%p Locale’s equivalent of a.m. or p.m. 


Time aS%1:%M:%S %p. 


$s 





%R Time as %H: sil. 

%S Seconds (0-61; leading zeroes are permitted but not required; extra second allowed for 
leap years). 

%T Time aS %H:%M:%s. 

ou W eekday number (0-6) with Sunday as the first day of the week. 

%X Date using locale’s date format. 

%X Time, using locale’s time format. 

sy Year within century (0-99; leading zeroes are permitted but not required. 
Unfortunately, this makes the assumption that we are stuck in the 20th century, as 
1900 is automatically added onto this number for the tm year field.) 

%6Y Year, including century (for example, 1988). 


Case isignored when matching items such as month or weekday names. 
The broken-down time structure tm is defined in <time.h> as follows: 


struct tm 

{ 
int tm_sec; /* seconds */ 
int tm_min; /* minutes */ 
int tm_hour; /* hours */ 
int tm_mday; /* day of the month */ 
int tm_mon; /* month */ 
int tm_year; /* year */ 
int tm_wday; /* day of the week */ 
int tm_yday; /* day in the year */ 
int tm_isdst; /* daylight saving time */ 

}; 

RETURN VALUE 


The strptime() function returns a pointer to the character following the last character in the string pointed to bybut. 


SEE ALSO 


strftime(3), time(2), setlocale(3), scanf(3) 


BUGS 


Thereturn values point to static data, whose contents are overwritten by each call. 


NOTES 
This function is only available in libraries newer than version 4.6.5. 
The function supports only those locales specified in 1ocale(7). 
GNU, 26 Septenber 1994 


strsep 


strsep— Extracts token from string 


SYNOPSIS 


#include <string.h> 
char *strsep(char **stringp, const char *delim); 
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DESCRIPTION 


The strsep() function returns the next token from the stringstringp which is ddimited by delim. The token is taminated 
with a \@ character and stringp isupdated to point past the token. 


RETURN VALUE 


The strsep() function returns a pointer to the token, or NULL if delim isnot found in stringp. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 


index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strspn(3), strstr(3), strtok(3) 
GNU, 12 April 1993 


strsignal 
strsignal— Returns string describing signal 


SYNOPSIS 


#include <string.h> 
char *strsignal(int sig); 
extern const char * const sys_siglist [] 


DESCRIPTION 


The strsignal() function returns a string describing the sgnal number passed in the argument si g. The string can only be 
used until the next call to strsignal(). 


Thearray sys_siglist holds the signal description strings indexed by signal numbe. 


RETURN VALUE 


The strsignal() function returns the appropriate description string, or an unknown signal message if the signal number is 
invalid. 


SEE ALSO 


psignal(3), strerror(3) 
GNU, 13 April 1993 


strspn, strcspn 
strspn, strespn— Search a string for a set of characters 


SYNOPSIS 


#include <string.h> 
size t strspn(const char *s, const char *accept ); 
size t strcspn(const char *s, const char *reject ); 


DESCRIPTION 
The strspn() function calculates the length of the initial segment of s, which consists entirdy of characters in accept. 
The strespn() function calculates the length of the initial segment of s, which consists entirely of characters not in reject. 


crtod 
RETURN VALUE 


The strspn() function returns the number of characters in the initial segment of s, which consist only of characters from 
accept. 


The strespn() function returns the number of characters in theinitial segment of s, which arenot in thestring reject. 


CONFORMS T0 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strstr(3), strtok(3) 
12 April 1993 


strstr 
strstr— Locates a substring 


SYNOPSIS 


#include <string.h> 
char *strstr(const char *haystack, const char *needle); 


DESCRIPTION 


Thestrstr() function finds the first occurrence of the substringneedie in thestring haystack. Theterminating \o characters 
are not compared. 


RETURN VALUE 


The strstr() function returns a pointer to the beginning of the substring, or NuLt if the substring is not found. 


SEE ALSO 


index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strtok(3) 
GNU, 12 April 1993 


strtod 


strtod— Converts ASCII string to double 
SYNOPSIS 


#include <stdlib.h> 
double strtod(const char *nptr, char **endptr ); 


DESCRIPTION 
The strtod() function converts the initial portion of the string pointed to by nptr to double representation. 
The expected form of the string is optional leading whitespace as checked by isspace(3), an optional plus (+) or minus sign 
(-) followed by a sequence of digits optionally containing a decimal point character, optionally followed by an exponent. An 


exponent consists of an E or e, followed by an optional plus or minus sign, followed by anonempty sequence of digits. If the 
localeis not C or POSIX, different formats may be used. 
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RETURN VALUES 


The strtod function returns the converted value, if any. 


If endptr iSnot NULL, a pointer to the character after the last character used in the conversion is stored in the location 
referenced by endptr. 


If no conversion is performed, zero is returned and the value of nptr is stored in the location referenced by endptr. 


If the correct value would cause overflow, plus or minus HuGE_VAL is returned (according to the sign of the value), and ERANGE 
is stored in errno. If the correct value would cause underflow, zero is returned and erance is stored in errno. 


ERRORS 


ERANGE Overflow or underflow occurred. 


CONFORMS TO 
ANSIC 


SEE ALSO 
atof(3), atoi(3), ato1(3), strtol(3), strtoul(3) 
BSD man page 4 M arch 1996 


strtok 


strtok— Extracts token from string 


SYNOPSIS 


#include <string.h> 
char *strtok(char *s, const char *delim); 


DESCRIPTION 


A token is anonempty string of characters not occurring in thestring de! i m, followed by \o or by acharacter occurring in 
delim. 


The strtok() function can be used to parse the strings into tokens. The first call to strtok() should haves as its first 
argument. Subsequent calls should have the first argument set to nuLL. Each call returns a pointer to the next token, or NULL 
when no more tokens are found. 


If atoken ends with a delimiter, this delimiting character is overwritten with a \o and a pointer to the next character is saved 
for the next call to strtok. The delimiter string de! i m may be different for each call. 


BUGS 


This function modifies its first argument. T he identity of the delimiting character is lost. 


RETURN VALUE 


The strtok() function returns a pointer to the next token, or NULL if there are no more tokens. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strstr(3) 
GNU, 10 February 1996 


¢rtoul 


strtol 


strtol— Converts a string to along integer 


SYNOPSIS 


#include <stdlib.h> 
long int strtol(const char *nptr, char **endptr ,int base); 


DESCRIPTION 
The strto1() function converts the string in nptr to along integer value according to the given base, which must be between 
2 and 36 inclusive or be the special value 0. 
The string must begin with an arbitrary amount of whitespace (as determined by isspace(3)) followed by a single optional + 
or - sign. If base iszero or 16, the string may then include aox prefix, and the number will be read in base 16; otherwise a 
zero base is taken as 10 (decimal) unless the next character is 0, in which case it is taken as 8 (octal). 


Theremainder of the string is converted to along int valuein theobvious manner, stopping at the first character that isnot 
a valid digit in the given base (In bases above 10, the letter a in either upper- or lowercase represents 10, B represents 11, and 
so forth, with z representing 35.) 

If endptr iSnot NULL, strto1() stores the address of the first invalid character in *endptr. If there were no digits at all, strto1() 
stores the original value of nptr in *endptr. (T hus, if *nptr isnot \o but **endptr is \@ on return, theentire string is valid.) 


RETURN VALUE 


The strto1() function returns the result of the conversion, unless the value would underflow or overflow. If an underflow 
Occurs, strtol() retUrnS LONG_MIN. If an overflow occurs, strtol() returns LONG MAX. In both cases, errno is set to ERANGE. 


ERRORS 





ERANGE The given string was out of range; the value converted has ben clamped. 
CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 
SEE ALSO 
atof(3), atoi(3), ato1(3), strtod(3), strtoul(3) 
BUGS 


Ignores the current locale. 
GNU, 10 June1995 


strtoul 


strtoul— Converts a string to an unsigned long integer. 


SYNOPSIS 
#include <stdlib.h> 
unsigned long int strtoul(const char *nptr, char **endptr, 
int base); 
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DESCRIPTION 


The strtou1() function converts the string in nptr to an unsigned long integer value according to the given base, which must 
be between 2 and 36 inclusive, or be the special value 0. 


The string must begin with an arbitrary amount of whitespace (as determined by isspace(3)) followed by a single optional + 
or - sign. If baseis zero or 16, the string may then include a ex prefix, and the number will be read in base 16; otherwise, a 
zero base is taken as 10 (decimal) unless the next character is 0, in which case it is taken as 8 (octal). 


The remainder of the string is converted to an unsigned long int value in the obvious manne, stopping at the first character 
that is not a valid digit in the given base (In bases above 10, the letter a in either upper- or lowercase represents 10, B 
represents 11, and so forth, with z representing 35.) 


If endptr iSnot NULL, strtoul() stores the address of the first invalid character in *endptr. If there were no digits at all, 
strtoul() stores the original value of nptr in *endptr. (T hus, if *nptr isnot \o but **endptr is \o on return, the entire string is 
invalid.) 


RETURN VALUE 


The strtou1() function returns athe the result of the conversion or, if there was a leading minus sign, the negation of the 
result of the conversion, unless the original (non-negated) value would overflow; in the latter case strtoul() returns 
ULONG_MAX and sets the global variableerrno to ERANGE. 


ERRORS 





ERANGE Thegiven string was out of range; the value converted has been clamped. 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


SEE ALSO 


atof(3), atoi(3), ato1(3), strtod(3), strto1(3) 
BUGS 
strtoul ignores the current locale. 
GNU, 29 March 1993 


strxfrm 

strxfrm— String transformation 
SYNO PSIS 

#include <string.h> 


size t strxfrm(char *dest, const char *src, size_t n); 


DESCRIPTION 


The strxfrm() function transforms thesrc string into aform such that the result of strcmp() on two strings that have been 
transformed with strxfrm() isthe same as the result of strco11() on the two strings before their transformation. T hefirst n 
characters of the transformed string are placed in dest. The transformation is based on the program’s current locale for 
category LC_COLLATE. (S€@ setlocale(3)). 


RETURN VALUE 


The strxfrm() function returns the number of bytes required to store the transformed string in dest excluding the terminat- 
ing \o character. If the value returned isn or more, the contents of dest are indeterminate. 


sysconf 


CONFORMS TO 
SVID 3, BSD 4.3, 1SO 9899 


NOTES 
The Linux C Library currently hasn’t implenented the complete PO SI X-collating. 
In the POSIX or C locales strxfrm() is equivalent to copying the string with strncpy(). 


SEE ALSO 


bemp(3), memcmp(3), strcasecmp(3), stremp(3), strcol1(3), setlocale(3) 
GNU, 12 April 1993 


Swab 


swab— Swaps adjacent bytes 


SYNOPSIS 


#include <string.h> 
void swab(const void *from, void*to, size_t n); 


DESCRIPTION 


The swab() function copies n bytes from the array pointed to by from to thearray pointed to by to, exchanging adjacent even 
and odd bytes. Thisfunction is used to exchange data between machines that have different low/high byte ordering. 


RETURN VALUE 


The swab() function returns no value. 


CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 


bstring(3) 
GNU, 13 April 1993 


syscont 


sysconf— Gets configuration information at runtime 


SYNOPSIS 


#include <unistd.h> 
long sysconf (int name); 


DESCRIPTION 


sysconf() provides a way for the application to determine values for systan limits or options at runtime 


T he equivalent macros defined in <unistd.h> can only give conservative values; if an application wants to take advantage of 
values that may change, a call to sysconf() can bemade, which may yidd more liberal results. 


For getting information about a particular file, see fpathconf() OF pathconf(). 
The following values are supported for name. First, the PO SIX.1_ compatible values: 


Part III: Library Functions 


_SC_ARG_MAX 
_SC_CHILD_MAX 
_SC_CLK_TCK 


_SC_STREAM_MAX 


_SC_TZNAME_MAX 
_SC_OPEN_MAX 
_SC_JOB_CONTROL 
_SC_SAVED_IDS 


_SC_VERSION 


N ext, the PO SIX.2 values: 
_SC_BC_BASE_MAX 


_SC_BC_DIM MAX 
_SC_BC_SCALE_MAX 
_SC_BC_STRING_MAX 


_SC_COLL_WEIGHTS MAX 


_SC_EXPR_NEST_MAX 


_SC_LINE MAX 
_SC_RE_DUP_MAX 


_SC_2 VERSION 
_SC_2 DEV 
_SC_2 FORT_DEV 


_SC_2_FORT_RUN 


The maximum length of the arguments to the exec() family of 
functions; the corresponding macro is ARG_MAX. 

The number of simultaneous processes per user ID ; the corresponding 
macro iS _POSIX_CHILD_MAX. 

Thenumbe of clock ticks per second; the corresponding macro is 
CLK_TCK. 

The maximum number of streams that a process can have open at any 
time The corresponding POSIX macro is stREAM_MAx; the 
corresponding standard C macro is FOPEN_MAX. 

The maximum number of bytes in atime zonename the 
corresponding macro is TZNAME_MAX. 

The maximum number of files that a process can have open at any 
time; the corresponding macro is _POSIX_OPEN_MAX. 

This indicates whether PO SIX-style job control is supported, the 
corresponding macro is _POS1X_JOB_CONTROL. 

Thisindicates whether a process has a saved set-user-ID and a saved 
set-group-!D ; the corresponding macro is_POSIX_SAVED_IDS. 

Indicates the year and month the PO SIX.1 standard was approved in 
the format yyy mu; the value 199009L indicates the most recent 
revision, 1990. 


Indicates the maximum obase value accepted by the bc(1) utility; the 
corresponding macro iS BC_BASE_MAX. 

Indicates the maximum value of elements permitted in an array by 
be(1); the corresponding macro is BC_DIM_MAX. 

Indicates the maximum scale value allowed by bc(1); the 
corresponding macro iSBC_SCALE_MAX. 

Indicates the maximum length of a string accepted by be(1); the 
corresponding macro iSBC_STRING_MAX. 

Indicates the maximum numbers of weights that can be assigned to an 
entry of the Lc_coLLaTe order keyword in the locale definition file; the 
corresponding macro iS COLL_WEIGHTS MAX. 

Is the maximum number of expressions that can be nested within 
parentheses by expr(1). The corresponding macro iSEXPR_NEST_MAX. 
The maximum length of a utility's input line length, athe from 
standard input or from a file. T hisincludes length for a trailing 
newline The corresponding macro iS LINE_MAX. 

The maximum number of repeated occurrences of a regular 
expression when the interval notation \{m,n\} is used. T he value of 
the corresponding macro is RE_DUP_MAX. 

Indicates the version of the PO SIX.2 standard in the format of 
YYYYMML. The corresponding macro is POS1x2_VERSION. 

Indicates whether the PO SIX.2 C language development facilities are 
supported. T he corresponding macro is Pos1x2_C_DEV. 

Indicates whether the PO SIX.2 FORTRAN devdopment utilities are 
supported. T he corresponding macro is PoS1x2_FORT_RUN. 

Indicates whether the PO SIX.2 FORTRAN runtimeutilities are 
supported. T he corresponding macro is POS1x2_FORT_RUN. 








closdog, openlog, syslog 


POSIX2_LOCALEDEF Indicates whether the PO SIX.2 creation of locates via locale(1) is 
supported. T he corresponding macro is POSIxX2_LOCALEDEF. 
_SC_2_SW_DEV Indicates whether the PO SIX.2 software devdopment utilities option 


is supported. The corresponding macro is Pos1x2_sW_DEV. 


RETURN VALUE 
The value returned is the value of the system resource, 1 if a queried option is available, a if it isnot, or -1 on error. The 
variable errno isnot set. 

CONFORMS TO 
POSIX.1, proposed PO SIX.2 


BUGS 


It is difficult use aRG_MAx because it is not specified how much of the argument space for exec() isconsumed by the user's 
environment variables. 


Somereturned values may be huge; they are not suitable for allocating memory. 
POSIX.2 isnot ye an approved standard; the information in this man page is subject to change. 


SEE ALSO 


be(1), expr(1), locale(1), fpathcont(3), pathcont(3) 
GNU, 18 April 1993 


Closelog, openlog, syslog 


closelog, openlog, syslog— Send messages to the system logger 


SYNOPSIS 


#include <syslog.h> 

void openlog( char *ident ,int option,int facility); 
void syslog( int priority, char *format, ...); 
void closelog( void ); 


DESCRIPTION 


closelog() closes the descriptor being used to write to the system logger. The use of closelog() is optional. 


openlog() Opens aconnection to the system logger for a program. T he string pointed to byi dent isadded to each message, 
and is typically set to the program name Values for option and facility aregiven in the next subsection. T he use of 
openlog() iS optiona; it will automatically be called by sys1og() if necessary, in which casei dent will default to NULL. 


syslog() generates a log message, which will be distributed by syslogd(8). priority isacombination of thefacility andthe 
level, values for which are given in the next subsection. T he remaining arguments are aformat , aS in printf(3) and any 
arguments required by thefor mat , except that thetwo characters %m will be replaced by the error message string (strerror) 
corresponding to the present value of errno. 


PARAMETERS 


This section lists the parameters used to set the values of option, facility, and priority. 
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OPTION 


The option argument to openiog() isan or of any of these: 


LOG_CONS 

LOG_NDELAY Open theconnection i 
first message is logged) 

LOG_PERROR Print to stderr as wall 

LOG_PID Include p1p with each 


FACILITY 


The facility argument is used to specify what type of program i 
that messages from different facilities will be handled different 


LOG_AUTH Securi 


instead) 


LOG_AUTHPRIV Securi 
LOG_CRON 


LOG_DAEMON 





LOG_KERN 


LoG_LOcAL® through 
LOG_LOCAL7 


LOG_LPR 
LOG_MAIL 

LOG_NEWS 
LOG_SYSLOG 
LOG_USER (default) 
LOG_UUCP 


Kerne 


LEVEL 


Write directly to system console if there is an error while sending to system logger 


mmediatedy (normally, the connection is opened when the 


message 


slogging the message. T his lets the configuration file specify 
y. 
ty/authorization messages (DEPRECATED US@ LOG_AUTHPRIV 


ty/authorization messages (private) 


Clock daemon (cron and at) 
Other system daemons 


messages 


Reserved for local use 


Line printer subsystem 

M ail subsystem 

Usenet news subsystem 

M essages generated internally by syslogd 
Generic user-level messages 

UUCP subsystem 


This determines the importance of the message. The levels, in order of decreasing importance, are 


LOG_EMERG 
LOG_ALERT 
LOG_CRIT 
LOG_ERR 
LOG_WARNING 
LOG_NOTICE 
LOG_INFO 
LOG_DEBUG 





HISTORY 
A syslog function call appeared in BSD 4.2. 


SEE ALSO 


logger(1), syslog. conf(5), sysloga(8) 


System is unusable 

Action must be taken immediately 
Critical conditions 

Error conditions 

Warning conditions 

Norma, but significant, condition 
Informational message 

D ebug-levea message 


Linux, 15 February 1994 
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system 
system— Executes a shell command 


SYNOPSIS 


#include <stdlib.h> 
int system (const char * string); 


DESCRIPTION 


system() executes a command specified in string by calling /bin/sh -c string, and returns after the command has been 
completed. D uring execution of the command, siccHLo will be blocked, and siarnT and stequrt will be ignored. 


RETURN VALUE 


The value returned is 127 if the execve() Call for /bin/sh fails, -1 if there was another error, and the return code of the 
command otherwise. 


If the value of string iSNULL, system() returns non-zero if the shal is available, and zero if not. 
system() does not affect the wait status of any other children. 


CONFORMS TO 
ANSI C, POSIX.1, proposed PO SIX.2, BSD 4.3 


BUGS 


Do not use system() from a program with suid or sgid privileges, because strange values for some environment variables 
might be used to subvert system integrity. U se the exec(2) family of functions instead, but not execip(2) or execvp(2). 


The check for the availability of /bin/sh isnot actually performed; it is always assumed to be available. 


It is possible for the shall command to return 127, so that code is not a sure indication that the execve() call failed; check 
errno to make sure 


SEE ALSO 
sh(1), exec(2), signal(2) 
GNU, 13 April 1993 


tan 


tan— T angent function 


SYNOPSIS 


#include <math.h> 
double tan(double x); 


DESCRIPTION 


The tan() function returns the tangent of x, where x is given in radians. 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 
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SEE ALSO 
acos(3), asin(3), atan(3), atan2(3), cos(3), sin(3) 
8 June1993 


tanh 


tanh— H yperbolic tangent function 


SYNOPSIS 


#include <math.h> 
double tanh(double x); 


DESCRIPTION 


The tanh() function returns the hyperbolic tangent of x, which is defined mathenatically as sinh(x) / cosh(x). 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 
acosh(3), asinh(3), atanh(3), cosh(3), sinh(3) 
13 June1993 


telldir 


telldir— Returns current location in directory stream 


SYNOPSIS 


#include <dirent.h> 
off t telldir(DIR *dir); 


DESCRIPTION 


The telldir() function returns the current location associated with the directory stream dir. 


RETURN VALUE 


The telldir() function returns the current location in the directory stream or -1 if an error occurs. 


ERRORS 


EBADF Invalid directory stream descriptor dir 


CONFORMS T0 
BSD 4,3 


SEE ALSO 


opendir(3), readdir(3), closedir(3), rewinddir(3), seekdir(3), scandir(3) 
31 March 1993 


termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospead, cfgeti soead, 
cfseti speed, cfsetospead, tcgetpgrp, tcsetpgrp 


tempnam 


tempnam— Creates aname for atenporary file 


SYNOPSIS 


#include <stdio.h> 
char *tempnam(const char *dir, const char *pfx); 


DESCRIPTION 


The tempnam() function generates a unique temporary filename using up to five characters of pfx, if it isnot NULL. The 
directory to place the file is searched for in the following order: 


1. Thedirectory specified by the environment variable twporr, if it is writable 
2. Thedirectory specified by the argument dir, if it isnot NULL 

3. Thedirectory specified by p_tmpdir 

4. Thedirectory \tmp 


The storage for the filename is allocated by mal1oc(), and so can be freed by the function free(). 


RETURN VALUE 


The tempnam() function returns a pointer to the unique temporary filename, or NULL if a unique filename cannot be 
generated. 


ERRORS 


EEXIST Unable to generate a unique filename 


CONFORMS TO 
SVID 3, BSD 4.3 


SEE ALSO 


mktemp(3), mkstemp(3), tmpnam(3), tmpfile(3) 
GNU, 3 April 1993 


termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcf lush, 
tcf low, cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, 
cfsetospeed, tcgetpgrp, tcsetpgrp 


termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed 
cfsetospeed, tcgetpgrp, tcsetpgrp— Get and set terminal attributes, line control, get and set baud rate get and set taminal 
foreground process group ID 


SYNOPSIS 


#include <termios.h> 
#include <unistd.h> 


int tcegetattr ( int fd, struct termios *termios p ); 

int tcsetattr ( int fd,int optional_actions, struct termios *termios p ); 
int tcsendbreak ( int fd,int duration ); 

int tcdrain ( int fd ); 

int tcflush ( int fd,int queue_selector ); 
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int tcflow ( int fd,int action ); 

int cfmakeraw ( struct termios *termios_p ); 

speed_t cfgetospeed ( struct termios *termios p ); 

int cfsetospeed ( struct termios *termios_p, speed_t speed ); 
speed _t cfgetispeed ( struct termios *termios p ); 

int cfsetispeed ( struct termios *termios_p, speed_t speed ); 
pid_t tcgetpgrp ( int fd ); 

int tcsetpgrp ( int fd, pid_t pgrpid ); 


DESCRIPTION 


The termios functions describe a general terminal interface that is provided to control asynchronous communications ports. 


M any of the functions described here have ater mi os_p argument that isa pointer to atermios structure. T his structure 
contains the following members: 


tcflag_t c_iflag; /* input modes */ 
tcflag_t c_oflag; /* output modes */ 
tcflag_t c_cflag; /* control modes */ 
tcflag_t c_lflag;/*localmodes*/ 

cc_t c_cc[NCCS]; /* control chars */ 


The c_iflag flag constants are 


IGNBRK Ignore BREAK condition on input. 

BRKINT If IGNBRK is not set, generate SIGINT ON BREAK Condition, else read BREAK as Character \o. 

IGNPAR Ignore framing errors and parity errors. 

PARMRK If IGNPAR isnot set, prefix acharacter with a parity error or framing error with \377 \o. 
If neither Tanpar nor PARMRK is Set, read a character with a parity error or framing error 
as \0. 

INPCK Enable input parity checking. 

ISTRIP Strip off eighth bit. 

INLCR Translate ni to cr on input. 

IGNCR Ignore carriage return on input. 

ICRNL Translate carriage return to newline on input (unless rencr is set). 

IUCLC M ap uppercase characters to lowercase on input. 

IXON Enable xon/xorF flow control on output. 

IXANY Enable any character to restart output. 

IXOFF Enable xon/xorF flow control on input. 

IMAXBEL Ring bell when input queue is full. 


The c_oflag flag constants are 


OPOST Enable implementation-defined output processing. 

OLCUC M ap lowercase characters to uppercase on output. 

ONLCR M ap nt to cr-NL on output. 

OCRNL M ap cr to NL on output. 

ONOCR Don’t output cr at column e. 

ONLRET Don't output cr. 

OFILL Send fill characters for a delay, rather than using a timed delay. 
OFDEL Fill character is ascii beL. If unset, fill character is AscII NUL. 
NLDLY N ewline delay mask. Values are NLo and NL1. 


CRDLY Carriage return delay mask. V alues are cro, CR1, CR2,OF CR3. 


termios, tcgetattr, tesetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospead, cfgeti soead, 
cfseti speed, cfsetospead, tcgetpgrp, tcsetpgrp 


TABDLY H orizontal tab dday mask. Values are TABO, TAB1, TAB2, TAB3, OF XTABS. A value of XTABS 
expands tabs to spaces (with tab stops every aight columns). 

BSDLY Backspace delay mask. V alues are Bso or BS1. 

VTDLY Vertical tab delay mask. Values are vTo or vT1. 

FFDLY Form feed delay mask. V alues are FFo Or FF1. 


The c_cflag flag constants are 


CSIZE Character size mask. Values are css, cS6, CS7,0r css. 

CSTOPB Set two stop bits, rather than one. 

CREAD Enable receiver. 

PARENB Enable parity generation on output and parity checking for input. 
PARODD Parity for input and output is odd. 

HUPCL Lower modem control lines after last process closes the device (hang up). 
CLOCAL Ignore modem control lines. 

CIBAUD M ask for input speeds (not used). 

CRTSCTS Flow control. 


The c_iflag flag constants are 


ISIG Whe any of the characters InTR, QUIT, SUSP, OF DSUSP are received, generate the 
corresponding signal. 

ICANON Enable canonical mode. This enables the special characters EoF, EOL, EOL2, ERASE, KILL, 
REPRINT, STATUS, and WERASE, and buffers by lines. 

XCASE If TCANON is also set, terminal is uppercase only. Input is converted to lowercase, exceot 


for characters preceded by \. On output, uppercase characters are preceded by \ and 
lowercase characters are converted to uppercase. 





ECHO echo input characters. 

ECHOE If IcANON is also set, the ERASE Character erases the preceding input character, and weRASE 
erases the preceding word. 

ECHOK If IcANON is also set, the KILL character erases the current line. 

ECHONL If IcANON is also set, echo the nL character even if EcHo is not set. 

ECHOCTL If EcHo is also set, asc1z control signals other than Tas, NL, START, and stop are echoed as 
“x, where x is the character with ASCII code ox10 greater than the control signal. For 
example, character x28 (Bs) is echoed as *H. 

ECHOPRT If ICANON and IECHO are also set, characters are printed as they are being erased. 

ECHOKE If TCANON is also set, KILL is echoed by erasing each character on theline, as specified by 
ECHOE and ECHOPRT. 

FLUSHO Output is being flushed. T his flag is toggled by typing the p1scarp character. 

NOFLSH Disable flushing the input and output queues when generating thesiainT and s1Gqurt 
signals, and flushing the input queue when generating the siesusp signal. 

TOSTOP Send the steTtou signal to the process group of a background process that tries to write 
to its controlling terminal. 

PENDIN All characters in the input queue are reprinted when the next character is read. (bash 
handles typeahead this way.) 

TEXTEN Enable implementation-defined input processing. 


tegetattr() gets the parameters associated with the object referred by fd and stores than in the termios structure referenced 
bytermios_p. 1 his function may beinvoked from a background process; however, the terminal attributes may be 
subsequently changed by a foreground process. 
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tesetattr() sets the parameters associated with the terminal (unless support is required from the underlying hardware that is 
not available) from the termios structure referred to by termi os_p. optional_actions specifies when the changes take effect: 


TCSANOW The change occurs immediately. 

TCSADRAIN The change occurs after all output written to ta has been transmitted. T his function 
should be used when changing parameters that affect output. 

TCSAFLUSH The change occurs after all output written to the object referred by fa has been 





transmitted, and all input that has been received but not read will be discarded 
before the change is made 


tcsendbreak() transmits a continuous stream of zero-valued bits for a specific duration, if the terminal is using asynchronous 
serial data transmission. If duration is zero, it transmits zero-valued bits for at least 0.25 seconds, and not more that 0.5 
seconds. If duration isnot zero, it sends zero-valued bits for duration*n seconds, wheren is at least 0.25, and not more than 
0.5. 


If the terminal is not using asynchronous sevial data transmission, tcsendbreak() returns without taking any action. 
tcdrain() waits until all output written to the object referred to by fa has been transmitted. 


tcflush() discards data written to the object referred to by fa but not transmitted, or data recaved but not read, depending 
on the value of queue_selector: 


TCIFLUSH Flushes data recaved but not read 
TCOFLUSH Flushes data written but not transmitted 
TCIOFLUSH Flushes both data received but not read, and data written but not transmitted 


tcflow() Suspends transmission or reception of data on the object referred to by fa, depending on the value of action: 


TCOOFF Suspends output 

TCOON Restarts suspended output 

TCIOFF Transmits a stop character, which stops the teminal device from transmitting 
data to the system 

TCION Transmits a start character, which starts the terminal device transmitting data 
to the system 


The default on open of a terminal file isthat nather its input nor its output is suspended. 


The baud rate functions are provided for getting and setting the values of the input and output baud rates in the termios 
structure. The new values do not take effect until tcsetattr() is successfully called. 


Setting the speed to Bo instructs the modem to hang up. The actual bit rate corresponding to 838400 may be altered with 
setserial(8). 


Theinput and output baud rates are stored in the termios structure 
cfmakeraw sets the terminal attributes as follows: 


termios_p->c_iflag &= ~(IGNBRK!BRKINT | PARMRK! ISTRIP 
'INLCR! IGNCR! ICRNL! IXON) ; 

termios_p->c_oflag &= “OPOST; 

termios_p->c_lflag &= ~(ECHO!ECHONL! ICANON!ISIG!IEXTEN) ; 
termios_p->c_cflag &= ~(CSIZE!PARENB) ; 
termios_p->c_cflag |=CS8; 


cfgetospeed() returns theoutput baud rate stored in the termios structure pointed to by termios_p. 


cfsetospeed() sets theoutput baud rate stored in the termios structure pointed to by termios_p to speed, which must be one 
of these constants: 
BO 


B50 
B75 


tmpfile 


B110 
B134 
B150 
B200 
B300 
B600 
B1200 
B1800 
B2400 
B4800 
B9600 
B19200 
B38400 
B57600 
B115200 
B230400 


The zero baud rate, Be, is used to terminate the connection. If Ba is specified, the modem control lines shall no longer be 
asserted. N ormally, this will disconnect the line. cBaupex is a mask for the speeds beyond those defined in PO SIX.1 (57600 
and above). T hus, 857600 & CBAUDEX iS non-zero. 


cfgetispeed() returns theinput baud rate stored in the termios structure. 


cfsetispeed() sets theinput baud rate stored in the termios structure to speed. If theinput baud rate is set to zero, the input 
baud rate will be equal to the output baud rate. 


tegetpgrp() returns process group |D of foreground processing group, or -1 on error. 
tesetpgrp() sets process group ID to pgrpid. pgrpid must be the|D of a process group in the same session. 


RETURN VALUES 


cfgetispeed() returns theinput baud rate stored in the termios structure. 
cfgetospeed() returns theoutput baud rate stored in the termios structure 





tegetpgrp() returns process group |D of foreground processing group, or -1 on error. 
All other functions return 


ft) On success 

“1 On failure and set errno to indicate the error 
SEE ALSO 

setserial(8) 


Linux, 2 Seotenber 1995 


tmpfile 


tmpfile— Creates a temporary file 


SYNOPSIS 


#include <stdio.h> 
FILE *tmpfile (void); 


DESCRIPTION 
The tmpfile() function generates a unique temporary filename using the path prefix p_tmpdir defined in <stdio.h>. The 
temporary file is then opened in binary read/write (w+b) mode. The file will be automatically dd ted when it is closed or the 
program terminates. 
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RETURN VALUE 


The tmpfile() function returns a stream descriptor, or N ULL if a unique filename cannot be generated or the unique file 
cannot be opened. 


ERRORS 
EACCES Search permission denied for directory in file’s path prefix 
EEXIST Unable to generate a unique fileaame 
EMFILE Too many file descriptors in use by process 
ENFILE Too many files open in system 
EROFS Read-only filesystem 

CONFORMS TO 

SVID 3, POSIX, BSD 4.3, 1SO 9899 
SEE ALSO 


mktemp(3), mkstemp(3), tmpnam(3), tempnam(3) 
GNU, 3 April 1993 


tmpnam 


tmpnam— Creates aname for a temporary file 


SYNOPSIS 


#include <stdio.h> 
char *tmpnam(char *s); 


DESCRIPTION 


The tmpnam() function generates a unique tenporary filename using the path prefix p_tmpdir defined in <stdio.h>. If the 
argument s iSNULL, tmpnam() returns the address of an internal static area that holds the filename, which is overwritten by 
subsequent calls to tmpnam(). If s isnot NuLL, the filename is returned ins. 


RETURN VALUE 


The tmpnam() function returns a pointer to the unique temporary filename, or NULL if a unique name cannot be generated. 


ERRORS 


EEXIST Unable to generate a unique filename 


CONFORMS TO 
SVID 3, POSIX, BSD 4,3, 1SO 9899 


SEE ALSO 


mktemp(3), mkstemp(3), tempnam(3), tmpfile(3) 
GNU, 3 April 1993 


toupper, tolower 


toascil 


toascii— Converts character to ASCII 


SYNOPSIS 


#include <ctype.h> 
int toascii (int c); 


DESCRIPTION 


toascii() converts c to a 7-bit unsigned char value that fits into the ASCII character set, by clearing the high-order bits. 


RETURN VALUE 


The value returned is that of the converted character. 


CONFORMS TO 
SVID, BSD 


BUGS 


M any people will be unhappy if you use this function. This function will convert accented letters into random characters. 


SEE ALSO 


isascii(3), toupper(3), tolower(3) 
GNU, 16 Septenber 1995 


toupper, tolower 


toupper, tolower— Convert letter to uppercase or lowercase 


SYNOPSIS 


#include <ctype.h> 
int toupper (int c); 
int tolower (int c); 


DESCRIPTION 
toupper() converts the letter to uppercase, if possible. 
tolower() converts the letter to lowercase, if possible. 


RETURN VALUE 


The value returned is that of the converted letter, orc if the conversion was not possible. 


CONFORMS TO 
ANSI C, BSD 4.3 


BUGS 


T he details of what constitutes an uppercase or lowercase letter depend on the current locale. For example, the default locale 
does not know about umlauts, so no conversion is done for then. 


In some non-English locales, there are lowercase letters with no corresponding uppercase equivalent; the G erman sharp sis 
one example. 
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SEE ALSO 


isalpha(3), setlocale(3), locale(7) 
GNU, 4 April 1993 


tsearch, tfind, tdelete, twalk 


tsearch, tfind, tdelete, twalk— M anage a binary tree 


SYNOPSIS 


#include <search.h> 

void *tsearch (const void *key ,void **rootp, 

int (*compar )(const void *, const void *)); 

void *tfind (const void *key, const void **rootp, 

int (*compar )(const void *, const void *)); 

void *tdelete (const void *key ,void**rootp, 

int (*compar )(const void *, const void *)); 

void twalk (const void *root ,void (*action)(const void*nodep, 
const VISIT which, 

const int depth)); 


DESCRIPTION 


tsearch, tfind, twalk, and tdelete manage a binary tree. They are generalized from Knuth (6.2.2) Algorithm T. The first 
fidd in each node of the tree isa pointer to the corresponding data item. (The calling program must store the actual data.) 
compar points to acomparison routine, which takes pointers to two items. It should return an integer that is negative zero, or 
positive, deoending on whether the first item is less than, equal to, or greater than the second. 


tsearch Searches the tree for an item. key points to the iten to be searched for. root p points to a variable that points to the 
root of the tree If the tree is empty, then the variable that root p points to should be set to nuLL. If the item is found in the 
tree, then tsearch returnsa pointer to it. If itis not found, then tsearch addsit, and returns a pointer to thenewly added 
iten. 

tfind is like tsearch, except that if theitem is not found, then tfind returns NULL. 

tdelete deletes an item from the tree Its arguments are the same as for tsearch. 


twalk performs depth-first, left-to-right traversal of a binary tree. root points to the starting node for the traversal. If that 
node isnot the root, then only part of the tree will be visited. twa1k calls the user function action each time a node is visited 
(that is, three times for an internal node, and once for a leaf). action, in turn, takes three arguments. T he first is a pointer to 
the node being visited. The second is an integer that takes on the values preorder, postorder, and endorder depending on 
whether thisisthe first, second, or third visit to the internal node or leaf if it isthe single visit to a leaf node. (T hese symbols 
are defined in <search.h>.) The third argument is the depth of the node, with zero being the root. 


RETURN VALUE 


tsearch returns a pointer to amatching item in the tree, or to the newly added item, or nuLt if there was insufficient memory 
to add the iten. tfind returns a pointer to the item, or nuLt if no match is found. If there are multiple elements that match 
the key, the dement returned is unspecified. 


tdelete returns a pointer to the parent of the item deeted, or nuLt if theiten was not found. 


tsearch, tfind, and tdelete also return NULL if root p WaSNULL On entry. 


WARNINGS 


twalk takes a pointer to the root, while the other functions take a pointer to a variable that points to the root. 


twalk US6S postorder to mean “after the left subtree, but before the right subtree” Some authorities would call this inorder, 
and reserve postorder to mean “after both subtrees.” 


tsearch, tfind, tddete twalk 


tdelete frees the manory required for the node in thetree T he user is responsible for freeing the memory for the 
corresponding data. 


The example program depends on the fact that twalk makes no further reference to anode after calling the user function 
with argument endorder or leaf. T his works with the GN U library implementation, but isnot in the SysV documentation. 


EXAMPLE 


The following program inserts twelve random numbers into a binary tree, then prints the numbers in order. The numbers 
are renoved from the tree and their storage freed during the traversal. 


#include <search.h> 
#include <stdlib.h> 
#include <stdio.h> 


void *root=NULL; 


void *xmalloc(unsigned n) 
{ 
void *p; 
p = malloc(n); 
if(p) return p; 
fprintf(stderr, “insufficient memory\n"); 
exit(1); 
} 


int compare(const void *pa, const void *pb) 
{ 
if(*(int *)pa < *(int *)pb) return -1; 
if(*(int *)pa > *(int *)pb) return 1; 
return 0; 


} 


void action(const void *nodep, const VISIT which, const int depth) 
{ 

int *datap; 

void *val; 


switch (which) 

{ 

case preorder: 
break; 

case postorder: 
datap = *(int **)nodep; 
printf("%6d\n", *datap); 
break; 

case endorder: 
datap = *(int **)nodep; 
(void)tdelete(datap, &root, compare); 
free(datap) ; 
break; 

case leaf: 
datap = *(int **)nodep; 
printf("%6d\n", *datap); 
val = tdelete(datap, &root, compare); 
free(datap); 
break; 

} 


return; 
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} 


int main() 

{ 
int i, *ptr; 
void *val; 


for (i = 0; i < 12; i++) 
{ 
ptr = (int *)xmalloc(sizeof(int)); 
*potr = rand()&Oxff; 
val = tsearch((void *)ptr, &root, compare); 
if(val == NULL) exit(1); 


ae action); 
return 0; 
} 
CONFORMS TO 
SVID 
SEE ALSO 


qsort(3), bsearch(3), hsearch(3), 1search(3) 
GNU, 24 Septenber 1995 


ttyname 


ttyname— Returnsname of a terminal 


SYNOPSIS 


#include <unistd.h> 
char *ttyname ( int desc ); 


DESCRIPTION 


Returns a pointer to the pathname of the terminal device that is open on the file descriptor desc, Or NULL On error (for 
example, if desc isnot connected to aterminal). 


CONFORMS TO 
POSIX.1 


SEE ALSO 


isatty(3), fstat(3) 
Linux, 20 April 1995 


tzset 


tzset— Initializes time conversion information 


SYNOPSIS 


#include <time.h> 
void tzset (void); 
extern char *tzname[2]; 


DESCRIPTION 


The tzset() function initializes thet zname variable from the Tz environment variable. T his function is automatically called 
by the other time conversion functions that depend on thetime zone 

If the Tz variable does not appear in the environment, thet zname variable is initialized with the best approximation of local 
wall clock time, as specified by the tzfile(5)-format file /usr/1ib/zoneinfo/localtime. 

If the tz variable does appear in the environment but its value is NULL or its value cannot be interpreted using any of the 
formats specified in the following paragraphs, Coordinated U niversal Time (UTC) is used. 

The value of Tz can be one of three formats. The first format is used when there is no daylight saving time in the local time 
zone: 

std offset 


Thestd string specifies the name of the time zone and must be three or more alphabetic characters. The offset string 
immediately follows std and specifies the time value to be added to the local timeto g& Coordinated Universal Time 
(UTC). The offset is positive if the local time zone is west of the Prime M evidian and negative if it is east. The hour must be 
between 0 and 24, and the minutes and seconds 0 and 59. 


The second format is used when there is daylight saving time: 


std offset dst [offset],start[/time] ,end[ /time] 


There are no spaces in the specification. The initial std and offset specify the standard time zone as described. The dst 
string and offset specify the name and offset for the corresponding daylight savings time zone. If the offset is omitted, it 
defaults to one hour ahead of standard time 


The start fidd specifies when Daylight Savings T ime goes into effect and the end fidd specifies when the change is made 
back to Standard Time. T hese fields may have the following formats: 


Jn This specifies the Julian day with n between 1 and 365. February 29 is never counted even in 
leap years. 

n This specifies the) ulian day with n between 1 and 365. February 29 is counted in leap years. 

Mm. w. d Thisspecifies day ¢ (0 <=d <=6) of week w (1 <=w <=5) of month m(1 <=m <=12). Wek 


1 is the first week in which day occurs and week 5 is the last week in which dayd occurs. 
Day 0 isa Sunday. 


The time fields specify when, in the local time currently in effect, the change to the other time occurs. If omitted, the default 
iS 02:00:00. 

The third format specifies that the time zone information should be read from a file 

:[filespec] 

If the file specification filespec is omitted, the time zone information is read from /usr/1lib/zoneinfo/localtime, which isin 


tzfile(5) format. If filespec is given, it specifies an-other tzfile(5)-format file to read the time zone information from. If 
filespec does not begin with a/, the file specification is rdative to the system time conversion information directory /usr/ 


lib/zoneinfo. 
FILES 
/usr/1ib/zoneinfo System time zone directory 
/usr/lib/zoneinfo/localtime Local time zone file 
/usr/1ib/zoneinfo/posixrules Rules for PO SIX-style Tzs 
CONFORMS TO 


SVID 3, POSIX, BSD 4.3 
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SEE ALSO 


date(1), gettimeofday(2), time(2), ctime(3), getenv(3), tztile(5) 
BSD, 2 July1993 


none 


none— Undocumented library functions 


SYNOPSIS 


Undocumented library functions 


DESCRIPTION 


This man page mentions those library functions that are implemented in the standard libraries but not yet documented in 
man pages. 


SOLICITATION 


If you have information about these functions, please look in the source code, writea man page (using a style similar to that 
of the other Linux section 3 man pages), and send it to aeb@cwi.n1 for inclusion in the next man page rd ease. 


THE LIST 


des_setparity, dn_skipname, ecb_crypt, encrypt, endnetgrent, endrpcent, endutent, execlp, fcrypt, fp_nquery, fp_query, 
fp_resstat, get_myaddress, getnetgrent, getnetname, getopt_long_only, getpublickey, getrpcbyname, getrpcbynumber, 
getrpcent, getrpcport, getsecretkey, getutid, getutline, h_errlist, host2netname, hostalias, inet_nsap_addr, 
inet_nsap_ntoa_init_des, innetgr, key_decryptsession, key_encryptsession, key_gendes, key_setsecret, lfind, libc_nls_init, 
lockf, lsearch, mcheck, memalign, mstats, mtrace, netname2host, netname2user, nlist, obstack_free, p_cdname, p_cdnname, 
p_class, p_fqname, p_option, p_query, p_rr, p_time, p_type, passwd2des, pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, 
pmap_unset, putlong, putshort, pututline, rcmd, re_compile_fastmap, re_compile pattern, re_match, re_match_2, re_rx_search, 
re_search, re_search_2, re_set_registers, re_set_syntax, registerrpc, res_send_setqhook, res_send_setrhook, rexec, 
rresvport, rtime, ruserok, ruserpass, setfileno, sethostfile, setkey, setlogmask, setnetgrent, setrpcent, setutent, 
siglongjmp, snprintf, stpcpy, svc_exit, svc_getreq, svc_getreqset, svc_register, svc_run, svc_sendreply, svc_unregister, 
svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth, 
svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate, svcudp_create, svcudp_enablecachesyscall, tdelete, tell, 
tfind, timegm, tr_break, tsearch, twalk, tzsetwall, ufc_dofinalperm, ufc_doit, user2netname, utmpname, valloc, vsnprintf, 
vsyslog, xdecrypt, xdr_accepted_reply, xdr_array, xdr_authdes_cred, xdr_authdes_verf, xdr_authunix_parms, xdr_bool, 
xdr_bytes, xdr_callhdr, xdr_callmsg, xdr_char, xdr_cryptkeyarg, xdr_cryptkeyres, xdr_datum, xdr_des_block, xdr_domainname, 
xdr_double, xdr_enum, xdr_float, xdr_free, xdr_getcredres, xdr_int, xdr_keybuf, xdr_keystatus, xdr_long, xdr_mapname, 
xdr_netnamestr, xdr_netobj, xdr_opaque, xdr_opaque_auth, xdr_passwd, xdr_peername, xdr_pmap, xdr_pmaplist, xdr_pointer, 
xdr_reference, xdr_rejected_reply, xdr_replymsg, xdr_rmtcall_args, xdr_rmtcallres, xdr_short, xdr_string, xdr_u_char, 
xdr_u_int, xdr_u_long, xdr_u_short, xdr_union, xdr_unixcred, xdr_vector, xdr_void, xdr_wrapstring, xdr_yp_buf, 
xdr_yp_inaddr, xdr_ypbind_binding, xdr_ypbind_resp, xdr_ypbind_resptype, xdr_ypbind_setdom, xdr_ypdelete_args, 
xdr_ypmaplist, xdr_ypmaplist_str, xdr_yppasswd, xdr_ypreq_key, xdr_ypreq_nokey, xdr_ypresp_all, xdr_ypresp_all_seq, 
xdr_ypresp_key_val, xdr_ypresp_maplist, xdr_ypresp_master, xdr_ypresp_order, xdr_ypresp_val, xdr_ypstat, 
xdr_ypupdate_args, xdrmem_create, xdrrec_create, xdrrec_endofrecord, xdrrec_eof, xdrrec_skiprecord, xdrstdio_create, 
xencrypt, xprt_register, xprt_unregister, yp_all, yp_bind, yp first, yp_get_default_domain, yp_maplist, yp_master, yp_match, 
yp_next, yp_order, yp_unbind, yp_update, yperr_string, ypprot_err 


Linux 1.3.15, 25 August 1995 


wctomb 


usleep 


usleep— Suspends execution for interval of microseconds 


SYNOPSIS 


#include <unistd.h> 
void usleep(unsigned long usec); 


DESCRIPTION 


Theusleep() function suspends execution of the calling process for usec microseconds. The sleep may be lengthened slightly 
by any system activity or by the time spent processing the call. 


CONFORMS TO 
BSD 4.3 


SEE ALSO 


setitimer(2), getitimer(2), sleep(3), alarm(3), select(3) 
4 july 1993 


westombs 


westombs— Converts a wide character string to a multibyte character string 


SYNOPSIS 


#include <stdlib.h> 
size_t wcestombs(char *s, const wchar_t *pwcs, size_t n); 


DESCRIPTION 


Thewestombs() function converts a sequence of wide characters from the array pwcs into a sequence of multibyte characters 
and stores up to n bytes of multibyte characters in the array s. 


RETURN VALUE 


westombs() returns the number of bytes stored ins or -1 ifs contains an invalid wide character. 


CONFORMS TO 
SVID 3,1S0 9899 


SEE ALSO 


mblen(3), mbtowc(3), mbstowcs(3), wetomb(3) 
GNU, 29 March 1993 


wetomb 


wetomb— C onverts a wide character to a multibyte character 


SYNOPSIS 


#include <stdlib.h> 
int wetomb(char *s, wchar_t wchar ); 
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DESCRIPTION 


Thewcetomb() function converts a wide character wehar into a multibyte character and, if sisnot NULL, stores the multibyte 
character representation ins. 


RETURN VALUE 


wetomb() returns thenumber of bytes in the multibyte character or -1 if the wide character is not valid. 


CONFORMS TO 
SVID 3,1SO 9899 


SEE ALSO 
mblen(3), mbstowcs(3), mbtowc(3), westombs(3) 
GNU, 29 March 1993 






Part IV: 


Special Files 


Part IV: Special Files 


INTRODUCTION 


This part describes special files. 


FILES 


/dev/* Device files 


AUTHORS 
Look at the header of the manual page for the author(s) and copyright conditions. N ote that these can be different from page 

to page. 
Linux, 24 July 1993 


charsets 


charsets— Programmer's view of character sets and internationalization 


DESCRIPTION 


Linux is an international operating system. Several of its utilities and device drivers (including the console driver) support 
multilingual character sets including Latin-alphabet letters with diacritical marks, accents, ligatures, and entire non-Latin 
alphabets including Greek, Cyrillic, Arabic, and H ebrew. 

This manual page presents a programmer’s-eye view of different character-set standards and how they fit together on Linux. 
Standards discussed include ASCII, 1SO 8859, KOI8-R, Unicode, |SO 2022, and |ISO 4873. 


ASCII 
ASCII (American Standard C ode for Information) is the original 7-bit character set, originally designed for American 
English. It is currently described by the ECM A-6 standard. 


An ASCII variant replacing the American crosshatch/octothorpe/hash pound symbol with the British pound-sterling symbol 
is used in G reat Britain; when needed, the American and British variants may be distinguished asU.S. ASCII and U.K. 
ASCII. 


As Linux was written for hardware designed in the U nited States, it nativdy supports U.S. ASCII. 


ISO 8859 
ISO 8859 is a series of 10 8-bit character sets, all of which have U.S. ASCII in their low (7-bit) half, invisible control 
characters in positions 128 to 159, and 96 fixed-width graphics in positions 160-255. 
Of these, the most important isISO 8859-1 (Latin-1). It isnativdy supported in the Linux console driver, fairly well 
supported in X11R6, and is the base character set of HTML. 


Console support for the other 8859 character sets is available under Linux through user-mode utilities (such as setfont(8)) 
that modify keyboard bindings and the EGA graphics table and employ the “user mapping” font table in the console driver. 


H ere are brief descriptions of each set: 
8859-1 (Latin-1) Latin-1 covers most W estern European languages such as Albanian, Catalan, Danish, 
Dutch, English, Faroese Finnish, French, German, Galician, Irish, Icelandic, Italian, 


Norwegian, Portuguese Spanish, and Swedish. The lack of theligatures D utch ij, 
French oe and old-style German quotation marks is tolerable. 


8859-2 (Latin-2) Latin-2 supports most Latin-written Slavic and Central European languages: Czech, 
German, H ungarian, Polish, Rumanian, Croatian, Slovak, and Slovene 

8859-3 (Latin-3) Latin-3 is popular with authors of Esperanto, Galician, M altese, and T urkish. 

8859-4 (Latin-4) Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. It is essentially 


obsolete; see 8859-10 (Latin-6). 


charsets 


8859-5 Cyrillic letters supporting Bulgarian, Byelorussian, M acedonian, Russian, Serbian, and 
Ukrainian. U krainians read the letter ghe with downstroke as heh and would need a ghe 
with upstroke to write a correct ghe (See the discussion of KO18-R in the next 


subsection.) 

8859-6 Supports Arabic. T he 8859-6 glyph table isa fixed font of separate letter forms, but a 
proper display engine should combine thee pairwise into initial, medial, and final 
forms. 

8859-7 Supports modern Greek. 

8859-8 Supports H ebrew. 

8859-9 (Latin-5) This is a variant of Latin-1 that replaces rarely used Icdandic letters with T urkish ones. 

8859-10 (Latin-6) Latin-6 adds the last Inuit (Greenlandic) and Sami (Lappish) letters that were missing in 


Latin 4 to cover the entire N ordic area. RFC 1345 listed a preliminary and different 
Latin 6. Skolt Sami still needs a few more accents than these. 


KO18-R 


KO18-R isanon-ISO character set popular in Russia. The lower half is U.S. ASCII; the upper is aC yrillic character set 
somewhat better designed than ISO 8859-5. 


Console support for KO 18-R is available under Linux through user-mode utilities that modify keyboard bindings and the 
EGA graphics table, and that employ the “user mapping” font table in the console driver. 


UNICODE 


Unicode (ISO 10646) is a standard that aims to unambiguously represent every known glyph in every human language. 
Unicode's native encoding is 32-bit (older versions used 16 bits). Information on U nicodeis available at http://www. 
unicode.com. 


Linux represents U nicode using the 8-bit U nicodeT ransfer Format (UT F-8). U TF-8 isa variable length encoding of 
Unicode. It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, and 
6 bytes for 31 bits. 


Le a, 1, x stand for azero, one, or arbitrary bit. A byte oxxxxxxx stands for the U nicode 00000000 oxxxxxxx, which codes the 
same symbol as the ASCII @xxxxxxx. Thus, ASCII goes unchanged into UT F-8, and people using only ASCII do not notice 
any change— not in code, and not in file size. 


A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy is assembled into oeeeexxx xxyyyyyy. A byte 1110xxxx iS 
the start of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled into xxxxyyyy yyzzzzzz. (W hen utTF-8 is used to code 
the 31-bit ISO 10646, then this progression continues up to 6-byte codes.) 


For 1SO -8859-1 users this means that the characters with high bit set now are coded with two bytes. This tends to expand 
ordinary text files by one or two percent. T here are no conversion problems, however, since the U nicode value of |SO -8859- 
1 symbols equals their 1SO -8859-1 value (extended by aight leading zero bits). For Japanese users, this means that the 16-bit 
codes now in common use will take three bytes, and extensive mapping tables are required. M any Japanese therefore prefer 
180 2022. 


N ote that UT F-8 is sef-synchronizing: 1@xxxxxx isa tail, any other byte is the head of acode. N ote that the only way ASCII 
bytes occur in aU TF-8 stream is as themsdves. In particular, there are no enbedded nus or /s that form part of some larger 
code. 


Because ASCII, and, in particular, nuL and /, are unchanged, the kernel does not notice that UT F-8 is being used. It does not 
care at all what the bytes it ishandling stand for. 


Rendering of Unicode data streams is typically handled through subfont tables that map a subset of U nicodeto glyphs. 
Internally, the kernel uses U nicode to describe the subfont loaded in video RAM. This meansthat in UTF-8 mode onecan 
use a character set with 512 different symbols. This is not enough for J apanese, Chinese, and K orean, but it is enough for 
most other purposes. 
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ISO 2022 AND ISO 4873 


ThelSO 2022 and 4873 standards describe a font-control model based on VT 100 practice This modd is (partially) 
supported by the Linux kernel and by xterm(1). It is popular in Japan and K orea. 


There are four graphic character sets, called GO, G1, G2, and G3, and oneof then is the current character set for codes with 
high bit zero (initially GO), and one of them is the current character set for codes with high bit one (initially G1). Each 
graphic character set has 94 or 96 characters, and is essentially a 7-bit character set. It uses codes either 040-0177 (041-0176) 
Or 0240-0377 (0241-0376). GO always has size 94 and uses codes 041-0176. 

Switching between character sets is done using the shift functions “N (so orLs1), “O (sr or Lso), Esc n (LS2), ESC o (LS3), ESC 
n (S82), 


ESC 0 ($S3), ESC ~ (LS1R), ESC } (LS2R), ESC ! (LS3R). The function Lsn makes character set Gn the current one for codes with 
high bit zero. The function Lsnr makes character set Gn the current one for codes with high bit one The function ssn makes 
character set Gn (n=2 or 3) the current one for the next character only (regardless of the value of its high order bit). 


A 94-character set is designated as Gn character set by an escape sequence esc ( xx (forGQ), Esc ) xx (forG1), esc * xx (for 
G2), Esc + xx (for G3), where xx isa symbol or a pair of symbols found in the!|SO 2375 International Register of C oded 
Character Sets. For example, esc ( @ selectsthe!SO 646 character set asGO, Esc ( a selects the U.K. standard character set 
(with pound instead of number sign), esc ( B sdects ASCII (with dollar instead of currency sign), esc ( m Sdects a character 
set for African languages, esc ( ! A selects the Cuban character set, and so on. 


A 96-character set is designated as Gn character set by an escape sequenceesc - xx (forG1), esc . xx (forG2) or esc / xx 
(for G3). For example esc - a sdects the H ebrew alphabet asG1. 


A multibyte character set is designated as Gn character set by an escape sequence Esc $ xx or Esc $ ( xx (forGO), Esc $ ) 
xx (for G1), Esc $ * xx (for G2), Esc $ + xx (for G3). For example, esc $ ( c sdects the Korean character set for GO. The 
J apanese character set sdiected by Esc $ B hasamorerecent version sdected by Esc & @ESC $B. 


ISO 4873 stipulates a narrower use of character sets, where G 0 is fixed (always ASCII), so that G1, G2, and G3 can only be 
invoked for codes with the high order bit set. In particular, “N and “O arenot used anymore Esc ( xx can be used only with 
Xx=B, and ESC ) xx, ESC * xx, ESC + xx are equivalent to Esc - xx, ESC . xx, aNd ESC / xx, respectively. 


SEE ALSO 


console(4), console _ioct1(4), console codes(4) 
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console— Consoleterminal and virtual consoles 


DESCRIPTION 


A Linux systen has up to 63 virtual consoles (character devices with major number 4 and minor number 1 to 63), usually 
called /dev/ttyn with 1 n 63. The current consoleis also addressed by /dev/console Or /dev/ttyo, thecharacter device with 
major number 4 and minor number 0. The device files /dev/* are usually created using the script mAKEDEV, Or uSINg mknod(1), 
usually with mode 0622 and owner root. tty. 


Before kernel version 1.1.54, thenumber of virtual consoles was compiled into thekernd (in tty.h: #define NR_CONSOLES 8) 
and could be changed by editing and recompiling because version 1.1.54 virtual consoles are created on-the-fly, as soon as 
they are needed. 


Common ways to start a process on a consoleare the following: 


m@ Teall init(8) (in inittab(5)) to start a getty(8) on the console 
m@ Ask open(1) to start a process on the console 
m@ Start x; it will find the first unused console and display its output there. (There is also the ancient doshe11(8).) 
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Common ways to switch consoles are the following: 


m UseAlt+Fn or Ctri+Alt+Fn to switch to console n; AltGr+Fn might bring you to console n+12 [here Alt and AltGr refer 
to the left and right Alt keys, respectively] 

m UseAlt+RightArrow or Alt+_eftArrow to cycle through the presently allocated consoles 

m Usethe program chvt(1). (The key mapping can be set by the user; see loadkeys(1); the preceding key combinations are 
according to the default settings.) 


The command disalloc(8) will free the memory taken by the scren buffers for consoles that no longer have any associated 
process. 


PROPERTIES 
Consoles carry alot of state. | hopeto document that some other time. T he most important fact is that the consoles simulate 
vt100 terminals. In particular, a console is reset to the initial state by printing the two characters ESC c. All escape sequences 
can be found in console codes(4). 


FILES 


/dev/console 
/dev/tty* 


SEE ALSO 


charsets(4), console codes(4), console ioct1(4), mknod(1), tty(4), ttys(4), getty(8), init(8), chvt(1), open(1), disalloc(8), 
loadkeys(1), resizecons(8), setfont(8), mapscrn(8) 


Linux, 31 October 1994 
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console_codes— Linux console escape and control sequences 


DESCRIPTION 


The Linux console implements a large subset of the VT 102 and ECM A-48/ISO 6429/AN SI X3.64 terminal controls, plus 
certain privatemode sequences for changing the color palette, character-set mapping, and so on. In the following tabular 
descriptions, the second column gives EC M A-48 or DEC mnemonics (the latter if prefixed with DEC) for the given 
function. Sequences without a mnemonic areneither ECM A-48 nor VT 102. 


After all the normal output processing has been done, and astream of characters arrives at the console driver for actual 
printing, the first thing that happens is a translation from the code used for processing to the code used for printing. 


If the consoleisin UTF-8 mode, then the incoming bytes are first assembled into 16-bit U nicode codes. O therwise, each 
byte is transformed according to the current mapping table (which translates it to aU nicode value). (See the “Character Sets” 
subsection for discussion.) 


In the normal case, the U nicode value is converted to a font index, and thisis stored in video memory, so that the corre 
sponding glyph (as found in video ROM ) appears on the screen. N ote that the use of U nicode (and the design of the PC 
hardware) allows the use of 512 different glyphs simultaneously. 


If the current U nicode value is acontrol character, or you are currently processing an escape sequence, the value will treated 
specially. Instead of being turned into a font index and rendered as a glyph, it may trigger cursor movenent or other control 
functions. (See the “Linux Console C ontrols” subsection.) 


It is generally not good practice to hardwire terminal controls into programs. Linux supports a terminfo(5) database of 
terminal capabilities. Rather than emitting console escape sequences by hand, you will almost always want to use a 
terminfo-aware scree library or utility such aSncurses(3), tput(1), or reset(1). 
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LINUX CONSOLE CONTROLS 


This section describes all the control characters and escape sequences that invoke special functions (that is, anything other 
than writing a glyph at the current cursor location) on the Linux console 


CONTROL CHARACTERS 
A character is a control character if (before transformation according to the mapping table) it has one of the 14 codes oo 
(NUL), @7 (BEL), @8 (BS), 09 (HT), @a (LF), Ob (VT), Oc (FF), @d (CR), @e (SO), OF (SI), 18 (CAN), 1a (SUB), 1b (ESC), 7f (DEL). Onecan 
set a display control characters mode (see below), and allow 07, a9, ab, 18, 1a, 7f to be displayed as glyphs. On the other 
hand, in UTF-8 mode all codes 0-1 are regarded as control characters, regardless of any display control characters mode. 
If you have a control character, it is acted upon immediately and then discarded (even in the middle of an escape sequence) 
and the escape sequence continues with the next character. (H owever, esc starts a new escape sequence, possibly aborting a 
previous unfinished one, and can and sus abort any escape sequence) The recognized control characters are BEL, BS, HT, LF, 
VT, FF, CR, SO, SI, CAN, SUB, ESC, DEL, CSI. T hey do what one would expect: 
BEL (0x07, *G) beeps. 
BS (0x08, *H) backspaces one column (but not past the beginning of the line). 
(oxe9, *1) goes to the next tab stop or to the end of the line if there is no earlier tab stop. 
(0x0A, *J), VT (0x@B, “K) and FF (oxec, *L) all givea linefead. 
CR (@xoD, *M) gives a carriage return. 
(ox@E, *N) activates the G1 character set, and if LF/nL (new line mode) is set, also a carriage return. 
(oxeF, *0) activates the GO character set. 


ESC SEQUENCES, NOT CSI SEQUENCES 


ESC c RIS R eset. 

ESC D IND Linefeed. 

ESC E NEL N ewline. 

ESC H HTS Se tab stop at current column. 

ESC M RI Reverse linefeed. 

ESC Z DECID DEC private identification. The kernd returns the string 
Esc [ ? 6 c, Claiming that it isa VT 102. 

ESC 7 DECSC Save current state (cursor coordinates, attributes, character 
sets). 

ESC 8 DECRG Restore most recently saved state. 

ESC [ CSI Control sequence introducer. 

ESC % Start sequence selecting character set. 

ESC % @ Select default (ISO 646/1SO 8859-1). 

ESC % G Sdect UT F-8. 

ESC % 8 Sdect UT F-8 (obsolete). 

ESC # 8 DECALN DEC screen alignment test: fill screen with Es. 

ESC ( Start sequence defining GO character set. 

ESC ( B Select default (ISO 8859-1 mapping). 

ESC ( 0 Sdect vt100 graphics mapping. 


ESC ( U 
ESC ( K 


ESC ) 


ESC > DECPNM 
ESC = DECPAM 
ESC ] Osc 


ECMA-48 CSI SEQUENCES 
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Sdect null mapping— straight to characte ROM. 

Sdect user mapping, the map that is loaded by the utility 
mapscrn(8). 

Start sequence defining G1 (followed by one of B, @, u, K, as 
above). 

Se& numeric keypad mode 

Sé application keypad mode. 

(Should be: O perating systen command) Esc ] P nrrggbb: 
set palette, with parameter given in 7 hexadecimal digits 
after the final p :-(. Haren isthe color (0-16), and rrggbb 
indicates the red/green/blue values (0-255). Esc ] rR: reset 
palette. 


csi (or Esc [) is followed by a sequence of parameters, at most npar(16), that are decimal numbers separated by semicolons. 
An empty or absent parameter is taken to bee. The sequence of parameters may be preceded by a single question mark. 


H owevey, after cst [ (or esc [ [) asingle character is read and this entire sequence is ignored. (T he idea is to ignore an 


echoed function key.) 


Theaction of acs1 sequence is determined by its final character. 











Character Function D esrription 
@ ICH Insert the indicated #of blank characters. 
A CUU M ove cursor up the indicated # of rows. 
B cuD M ove cursor down the indicated # of rows. 
C CUF M ove cursor right the indicated # of columns. 
D CUB M ove cursor left the indicated # of columns. 
E CNL M ove cursor down the indicated # of rows, to column 1. 
F CPL M ove cursor up the indicated # of rows, to column 1. 
G CHA M ove cursor to indicated column in current row. 
H CUP M ove cursor to the indicated row, column (origin at 1,1). 
J ED Erase display (default: from cursor to end of display). 
ESC [ 1 uJ: erase from start to cursor. 
ESC [ 2 uJ: erase whole display. 
K EL Erase line (default: from cursor to end of line). 
ESC [ 1 K: erase from start of line to cursor. 
ESC [ 2 k: erase whole line. 
L IL Insert the indicated #of blank lines. 
M DL D elete the indicated # of lines. 
P DCH D elete the indicated # of characters on the current line. 
x ECH Erase the indicated # of characters on the current line 
a HPR M ove cursor right the indicated # of columns. 
c DA Answer ESC [ ? 6 c: ‘I am a VT102', 
d VPA M ove cursor to the indicated row, current column. 
e VPR M ove cursor down the indicated # of rows. 
f HVP M ove cursor to the indicated row, column. 


continues 
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Character Function D esrription 
g TBC W ithout parameter: clear tab stop at the current position. 
Esc [ 3 g: ddeeall tab stops. 
h SM Se& mode 
1 RM Reset mode. 
m SGR Sé attributes. 
n DSR Status report. 
q DECLL Se keyboard LEDs. 
Esc [ 0 q: Clear all LEDS 
ESC [ 1 q: set Scroll Lock LED 
Esc [ 2 qi: set Num Lock LED 
Esc [ 3 q: set CapsLock LED 
r DECSTBM Sé scrolling region; parameters are top and bottom row. 
s 2 Save cursor location. 
u 2 Restore cursor location. 
' HPA M ove cursor to indicated column in current row. 


ECMA-48 SET GRAPHICS RENDITION 
TheECMA-48 SGR sequence Esc [ <parameters> m Sets display attributes. Several attributes can be set in the same 





sequence. 
Parameter Result 
Q Reset all attributes to their defaults. 
1 Sé& bold. 
2 Sé& half-bright (simulated with color on a color display). 
4 Se underscore (Simulated with color on acolor display). 
(The colors used to simulate dim or underline are set using Esc ] ....) 
5 Sé blink. 
7 Set reverse video. 
10 Reset sdected mapping, display control flag, and toggle meta flag. 
11 Sdect null mapping, set display control flag, reset toggle meta flag. 
12 Sdect null mapping, set display control flag, set toggle meta flag. (T he toggle meta flag 
causes the high bit of a byte to be toggled before the mapping table translation is done) 
21 Se normal intensity. (Thisis not compatible with EC M A-48.) 
22 Se normal intensity. 
24 Underline off. 
25 Blink off. 
27 Reverse video off. 
30 Se black foreground. 
31 Set red foreground. 
32 Se green foreground. 
33 Se brown foreground. 
34 Sé& blue foreground. 
35 Se magenta foreground. 
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Parameter Result 
36 Sé cyan foreground. 
37 Se white foreground. 
38 Se underscore on, set default foreground color. 
39 Se underscore off, set default foreground color. 
40 Sé& black background. 
41 Sé red background. 
42 Sé green background. 
43 Se brown background. 
44 Sé& blue background. 
45 Set magenta background. 
46 Sé cyan background. 
47 Sé white background. 
49 Sé default background color. 
ECMA-48 MODE SWITCHES 
ESC [ 3h peccrM (default off): Display control chars. 
ESC [ 4h pecim (default off): Set insert mode 
ESC [ 20h LF/NL (default off): Automatically follow echo of Lr, vt, or FF with cr. 


ECMA-48 STATUS REPORT COMMANDS 


ESC 
ESC 





5 
6 


n 


n 


D evice status report (D SR): Answer isesc [ @ n (Terminal OK). 


Cursor position report (CPR): Answer isesc [ y ; x R, wherex, y isthe cursor 
location. 


DEC PRIVATE MO DE(DECSET/DECRST) SEQUENCES 
These are not described in ECM A-48. The Set M ode sequences are listed; the Reset M ode sequences are obtained by 


replacing the final h by 1. 


ESC 


ESC 


ESC 


ESC 


ESC 


ESC 


ESC 


ESC 
ESC 





? 


? 


~ 


dieh: 


3h 


5h 


6h 


7h 


25h 
1000 h 


peEcckm (default off): W hen set, the cursor keys send an esc o prefix, rather than 
ESC [. 


peccoLm (default off =80 columns): 80/132 col mode switch. T he driver sources note 
that this alone does not suffice; some user-mode utility such as resizecons(8) has to 


change the hardware registers on the console video card. 
pecscnm (default off): Set reverse-video mode. 


pEcom (default off): When set, cursor addressing is relative to the upper left corner of 


the scrolling region. 


pecawm(default on): Set autowrap on. In this mode, a graphics character emitted after 
column 80 (or column 132 of peccoLm ison) forces a wrap to the beginning of the 


following line first. 
pecarM (default on): Set keyboard autorepreat on. 


h x10 M ouse Reporting (default off): Set reporting mode to 1 (or reset to @). 
(See “M ouseT racking.”) 


peccm (default on): M ake cursor visible 


x11 M ouse Reporting (default off): Set reporting mode to 2 (or reset to 0). 
(See “M ouseT racking.”) 
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LINUX CONSOLE PRIVATE CSI SEQUENCES 


The following sequences are ndther ECM A-48 nor native VT 102. They are native to the Linux console driver. Colors arein 
SGR parameters: 0 =black, 1 =red, 2 =green, 3 =brown, 4 =blue 5 =magenta, 6 =cyan, 7 =white 





ESC [ 1; ] Sé@ color n as the underline color 
ESC [2;n] Sé color n asthe dim color 
ESC [ 8 ] M ake the current color pair the default attributes 
ESC [9;n] Se screen blank time-out to n minutes 
ESC [ 10; n ] Sé& bal frequency in Hz 
ESC [ 11; n ] Sé bal duration in msec 
ESC [ 12; n ] Bring specified console to the front 
ESC [ 13 ] Unblank the screen 
ESC [ 14 ] Se the VESA powerdown interval 
CHARACTER SETS 


The kernel knows about four translations of bytes into consolescreen symbols. The four tables are 


m Latinl to PC 

m VT100 graphics to PC 
m PC to PC 

m User-defined 


There are two character sets, called GO and G1, and one of them isthe current character set. (Initially GO.) T yping *\ causes 
G1 to become current, *0 causes GO to become current. 


T hese variables co and a1 point to a translation table, and can be changed by the user. Initially, they point at the first two 
tables, Latinl to PC and VT 100 graphics to PC, respectively. The sequences esc ( Band esc ( @ andesc ( uandesc ( K 
cause Go to point at the first, second, third, and fourth translation tables in the preceding list, respectively. T he sequences Esc 
) Band esc ) @andesc ) u andesc ) k causeai to point at the first, second, third, and fourth translation tables in the 
preceding list, respectively. 


T he sequence Esc c causes a terminal reset, which is what you want if the screm is all garbled. The oft-advised “echo *v*0” 
will only make GO current, but there is no guarantee that ce points at the first table. In some distributions there is a program 
reset(1) that just does echo “[c. If your terminfo entry for the console is correct (and hasan entry rsi=c), then tput reset 
will also work. 


Theuser-defined mapping table can be set using mapsern(8). T he result of the mapping is that if a symbol c is printed, the 
symbol s = map[{c] issent to the video memory. The bitmap that corresponds to s isfound in the character rom, and can be 
changed using setfont(8). 


MOUSE TRACKING 


The mouse tracking facility is intended to return xterm-compatible mouse status reports. Because the console driver has no 
way to know the device or type of the mouse, these reports are returned in the console input stream only when the virtual 
terminal driver receives a mouse update ioctl. These ioctls must be generated by a mouse aware user-mode application such 
as the gpm(8) daemon. 


Parameters for all mouse tracking escape sequences generated by xterm encode numeric parameters in a single character as 
value+040. For example, ! is 1. The screm coordinate systen is 1-based. 


The x10 compatibility mode sends an escape sequence on button press encoding the location and the mouse button pressed. 
It is enabled by sending esc [ ? 9 hand disabled with esc | 2? 9 1. On button press, xterm sends esc [ Mm bxy (SIX charac- 
ters). Here b isbutton 1, and x and y are thex and y coordinates of the mouse when the button was pressed. T his is the same 
code the kernd also produces. 
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Normal tracking mode (not implenented in Linux 2.0.24) sends an escape sequence on both button press and rdease. 

M odifier information is also sent. It isenabled by sending esc [| ? 1000 hand disabled with esc [ 1000 1.O0n button press 
or release, xterm Sends esc [ m bxy. Thelow two bits of b encode button information: o=M B1 pressed, 1=M B2 pressed, 

2=M B3 pressed, 3=release T heupper bits encode what modifiers were down when the button was pressed and are added 
together: 4=Shift, 85M eta, 16=C ontrol. Again, x and y arethex and y coordinates of the mouse event. T he upper-left corner 
is (1,1). 


COMPARISONS WITH OTHER TERMINALS 


M any different terminal types are described, like the Linux console, as being VT 100-compatible. H ere we discuss differences 
between the Linux console and the two most important others, the DEC VT 102 and xterm(1). 


CONTROL-CHARACTER HANDLING 

The vt102 also recognized the following control characters: 

NUL (@x@@) was ignored. 

ENQ (0x05) triggered an answerback message. 

DC1 (@x11, “Q, XON) resumed transmission. 

DC3 (@x13, “S, XOFF) Caused vt100 to ignore (and stop transmitting) all codes except xorF and xon. 

vt100-like bc1/Dc3 processing may be enabled by the tty driver. 

The xterm program (in vt1ee mode) recognizes the control characters BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC. 
ESCAPE SEQUENCES 

The following VT 100 console sequences are not implemented on the Linux console: 





Escape Sequence Function D exrription 

ESC N ss2 Single shift 2. (Select G2 character set for the next 
character only.) 

ESC 0 $s3 Single shift 3. (Select G3 character set for the next 
character only.) 

ESC P DCs Device control string (ended by esc \). 

ESC X sos Start of string. 

ESC * PM Privacy message (ended by esc\). 

ESC \ ST String terminator. 

ESC * ... Designate G 2 character set. 

ESC +... D esignate G 3 character set. 


The program xterm (in vt1e@ mode) recognizeseEsc c, ESC # 8, ESC >, ESC =, ESC D, ESC E, ESC H, ESC M, ESC N, ESC 0, ESC P 

. ESC Esc z (it answersesc [ ? 1 ; 2c, “Il am avtl00 with advanced video option”) andesc * ... esc with the same 
meanings as indicated above. It accepts esc (, Esc ), Esc *, ESC + followed by @, a, B for the pec special character and line 
drawing set, uk, and usascit, respectively. It accepts esc j for the setting of certain resources: 


ESC ] 0 ; txt BEL Se icon name and window title to txt. 

ESC ]1 ; txt BEL Se icon name to txt. 

ESC ] 2; txt BEL Se window title to txt. 

ESC ] 4 6 ; name BEL Change log file to name (normally disabled by a compile-time option). 
ESC ] 50; fn BEL Set font to fn. 


It recognizes the following with slightly modified meaning: 


ESC 7 DECSC Save cursor 
ESC 8 DECRC Restore cursor 
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It also recognizes 


ESC F Cursor to lower-left corner of screen (if enabled by the 
hpLowerleftBugCompat resource). 

ESC 1 M emory lock (per H P terminals). Locks memory above the 
cursor. 

ESC m Memory unlock (per H P terminals). 

ESC n Ls2 Invoke the G2 character set. 

ESC o LS3 Invoke the G3 character set. 

ESC j LS3R Invoke the G 3 character set as car. 
Has no visible effect in xterm. 

ESC g LS2R Invoke the G2 character set as cr. 
Has no visible effect in xterm. 

ESC ~ LS1R Invoke the G 1 character set as Gr. 





Has no visible effect in xterm. 
It does not recognizeesc % ... 


CSI SEQUENCES 


The xterm program (as of xFrees6 3.1.2G) does not recognize the blink or invisiblemode SGRs. Stock X11R6 versions do 
not recognize the color-setting SGRs. All other ECM A-48 cs1 sequences recognized by Linux are also recognized by xterm, 
and vice versa. 


The xterm program will recognize all of the DEC Private M ode sequences listed earlier, but none of the Linux private mode 
sequences. For discussion of xterm’s own private mode sequences, refer to the Xterm Control Sequences document by Edward 
M oy and Stephen Gildea, available with thex distribution. 


BUGS 


In 2.0.23, cst isbroken, and nut isnot ignored inside escape sequences. 


SEE ALSO 


console(4), console _ioct1(4), charsets(4) 
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console ioctis— loctls for console terminal and virtual consoles 


DESCRIPTION 


The following Linux-peculiar ioct1() requests are supported. Each requires athird argument, assumed here to be argp. 


If you use the following information, you are going to burn yourself. | octls are undocumented Linux internals, liable to 
be changed without warning. Use POSIX functions. 
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KDGETLED Get state of LEDs. argp points to along int. The lower three bits of *argp are set to 
the state of the LEDs, as follows: 
LED_CAP 0x04 caps lock LED 
LEC_NUM 0x02 num lock LED 
LED_SCR x01 scroll lock LED 
KDSETLED Set the LEDs. The LED sare set to correspond to the lower three bits of argp. 


H owever, if ahigher order bit is set, the LEDs revet to normal, displaying the state 
of the keyboard functions of caps lock, num lock, and scroll lock. 
Before 1.1.54, the LED s just reflected the state of the corresponding keyboard flags, 
and KDGETLED/KDSETLED would also change the keyboard flags. Since 1.1.54 the LEDs 
can be made to display arbitrary information, but by default they display the 
keyboard flags. T he following two ioctls are used to access the keyboard flags. 
KDGKBLED Get keyboard flags capsLock, NumLock, ScrollLock (not lights). argp points to achar 
that is set to the flag state T he low order three bits (mask @x7) get the current flag 
state, and the low order bits of the next nibble (mask x7e) get the default flag state 
(since 1.1.54). 





KDSKBLED Se keyboard flags capsLock, NumLock, ScrollLock (not lights). argp has the desired 
flag state. The low order three bits (mask 0x7) have the flag state and the low order 
bits of the next nibble (mask x7@) have the default flag state (since 1.1.54). 
KDGKBTYPE Get keyboard type This returns the value kB 101, defined as oxo. 
KDADDIO Add 1/0 port as valid. Equivalent to ioperm(arg,1,1). 
KDDELIO Delete 1/O port as valid. Equivalent to ioperm(arg,1,0). 
KDENABIO Enablel/O to video board. Equivalent to ioperm(0x3b4, @x3df-0x3b4+1, 1). 
KDDISABIO Disable l/O to video board. Equivalent to ioperm(@x3b4, Ox3df-Ox3b4+ 1, 0). 
KDSETMODE Se text/graphics mode. argp is one of these: 
KD_TEXT 0x00 
KD_GRAPHICS 0x01 
KDGETMODE Get text/graphics mode. argp points to along which is set to one of the above values. 
KDMKTONE Generate tone of specified length. T he lower 16 bits of argp specify the period in 


clock cycles, and the upper 16 bits give the duration in msec. I f the duration is zero, 
the sound is turned off. Control returnsimmediatdy. For example, argp = (125<<16) 
+ @x637 would specify the beep normally associated with actri-c. 

KIOCSOUND Start or stop sound generation. T he lower 16 bits of argp specify the period in clock 
cycles (that is, argo =1193180/frequency). argp = @ turns sound off. In eather case, 
control returns immediately. 


GIO_CMAP Get the current default color map from kernd. argp points to a 48-byte array. 
(Since 1.3.3.) 
PIO_CMAP Change the default text-mode color map. argp points to a 48-byte array that 


contains, in order, the red, green, and blue values for the 16 available screen colors: @ 
is off, and 255 is full intensity. The default colors are in order: black, dark red, dark 
green, brown, dark blue dark purple, dark cyan, light grey, dark grey, bright red, 
bright green, yellow, bright blue, bright purple, bright cyan, and white (Since 
1.3.3.) 

GIO_FONT Gets 256-character screen font in expanded form. argp points to an 8192-byte array. 
Fails with error code ernva if the currently loaded font is a512-character font, or if 
the console is not in text mode 
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GI0_FONTX 


PIO_FONT 


PIO_FONTX 


PIO_FONTRESET 
GIO_SCRNMAP 


GIO_UNISCRNMAP 


PIO_SCRNMAP 


PIO_UNISCRNMAP 


GIO_UNIMAP 


PIO_UNIMAP 


Gets screen font and associated information. argp points to a struct consolefontdesc 
(see PIO_FONTX). On call, the charcount field should be set to the maximum number 
of characters that would fit in the buffer pointed to by chardata. On return, the 
charcount and charheight are filled with the respective data for the currently loaded 
font, and the chardata array contains the font data if the initial value of charcount 
indicated enough space was available, otherwise the buffer is untouched and errno is 
set to Enomem. (Since 1.3.1.) 

Sets 256-character screen font. Load font into the EGA/VGA character generator. 
argp points to a8192-byte map, with 32 bytes per character. O nly first n of them are 
used for an sxn font (@ < N <= 32). This call also invalidates the U nicode mapping. 
Sets screen font and associated rendering information. argp points to a 


struct consolefontdesc { 
u_short charcount; /* characters in font 


(256 or 512) */ 
u_short charheight ; /* scan lines per 


character (1-32) */ 
char *chardata; /* font data in 


expanded form */ 
}; 


If necessary, the screen will be appropriately resized, and stewrncH sent to the 
appropriate processes. This call also invalidates the U nicode mapping. (Since 1.3.1.) 
Resets the screen font, size, and Unicode mapping to the bootup defaults. argp is 
unused, but should be set to nuLt to ensure compatibility with future versions of 
Linux. (Since 1.3.28.) 

Get screen mapping from kernd.. argp points to an area of size E_TABSsz, which is 
loaded with the font positions used to display each character. This call is likely to 
return useless information if the currently loaded font is more than 256 characters. 
Get full Unicode screen mapping from kernd.. argp points to an area of size 
E_TABSZ*sizeof (unsigned short), which isloaded with the U nicodes each character 
represent. A special set of U nicodes, starting at u+Fo0e, are used to represent “direct 
to font” mappings. (Since 1.3.1.) 

Loads the user-definable (fourth) table in the kernel that maps bytes into console 
screen symbols. argp points to an area of size E_TABSZ. 

Loads the user-definable (fourth) table in the kernel that maps bytes into U nicodes, 
which are then translated into screen symbols according to the currently loaded 
Unicode-to-font map. Special U nicodes starting at u+Feee can be used to map 
directly to the font symbols. (Since 1.3.1.) 

et U nicode-to-font mapping from kernd. argp points to a 

ruct unimapdesc { 


| Short entry_ct; 
ruct unipair *entries ; 


() 


Ssevrunec on 


} 

here entries points to an array of 
struct unipair { 

u_short unicode; 

u_short fontpos; 

}; 

(Since 1.1.92.) 





Put Unicode-to-font mapping in kernel. argp points to a struct unimapdesc. 
(Since 1.1.92.) 
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PIO_UNIMAPCLR Clear table, possibly advise hash algorithm. argp pointsto a 


struct unimapinit { 

u short advised hashsize; /* ® if no opinion */ 
u short advised hashstep; /* @ if no opinion */ 
u short advised hashlevel; /* @ if no opinion */ 
}; 

(Since 1.1.92.) 


KDGKBMODE Gets current keyboard mode. argp points to a long, which is set to one of these: 
K_RAW 0x00 
K_XLATE 0x01 
K_MEDIUMRAW 0xe2 
K_UNICODE 0x03 
KDSKBMODE Sets current keyboard mode. argp is along equal to one of the above values. 
KDGKBMETA Gets meta key handling mode. argp points to along which is set to one of these: 
K_METABIT 0x03 Sé& high order bit 
K_ESCPREFIX 0x04 Escape prefix 
KDSKBMETA Sets meta key handling mode. argp is along equal to one of the preceding values. 
KDGKBENT Gets one entry in key translation table (keycode to action code). argp points to a 


struct kbentry { 
u_char kb_table; 
u_char kb_index; 
u_short kb_value; 
hs 
with the first two members filled in: kb table selects the key table (o <= kb_table 
<MAX_NR_KEYMAPS), and kb_index isthe keycode (a <= kb index <NR_KEYS). kb value iS 
set to the corresponding action code, or K_HOLE if thereisno such Key, or K_NOSUCHMAP 
if kb_table isinvalid. 
KDSKBENT Sets one entry in translation table. argp points to astruct kbentry. 
KDGKBSENT Gets one function key string. argp points to a 
struct kbsentry { 
u_char kb_func; 
u_char kb_string[512]; 
kb_string is set to the (NuLL-terminated) string corresponding to thekb_functh 
function key action code. 
KDSKBSENT Sets one function key string entry. argp points to a struct kbsentry. 
KDGKBDIACR Read kernd accent table. argp points to a 
struct kbdiacrs { 
unsigned int kb_cnt; 
struct kbdiacr kbdiacr[ 256]; 
hs 
where kb_ent isthe number of entries in the array, each of which isa 
struct kodiacr {u_char diacr, base, result ;} 
KDGETKEYCODE Read kernd keycode table entry (scan code to keycode). argp points to a 
struct kbkeycode {unsigned int scancode, keycode; } 


keycode iS set to correspond to the given scancode.(89<=scancode <= 255 only. 
For 1 <= scancode <= 88, keycode==scancode.) (Since 1.1.63.) 


KDSETKEYCODE Write kernel keycodetable entry. argp points to struct kbkeycode. (Since 1.1.63.) 
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KDSIGACCEPT 


VT_OPENQRY 


VT_GETMODE 


VT_SETMODE 
VT_GETSTATE 


VT_RELDISP 
VT_ACTIVATE 
VT_WAITACTIVE 
VT_DISALLOCATE 
VT_RESIZE 


VT_RESIZEX 


The calling process indicates its willingness to accept the signal argp when it is 
generated by pressing an appropriate key combination. (1 <= argp <=NSIG). 
(Se@ spawn_console() in linux/drivers/char/keyboard.c.) 

Returns the first available (nonopened) console. argp points to an int that is set to 
thenumber of the vt (1 <= *argp <=MAX_NR_CONSOLES). 

Get mode of active vt. argp points to a 

struct vt mode { 

char mode; /*vtmode*/ 

char waitv; /* if set, hang on writes if not active */ 

short relsig; /* signal to raise on release req */ 

short acqsig; /* signal to raise on acquisition */ 

short frsig; /* unused (set to 0) */ 

hs 


mode is set to one of these values: 


VT_AUTO Auto vt switching 
VT_PROCESS Process controls switching 
VT_ACKACQ Acknowledge switch 


Set mode of active vt. argp points to a struct vt_mode. 
Get global vt stateinfo. argp points to a 


struct vt_stat { 

ushort v_active; /* active vt */ 

ushort v_signal;/*signalto send*/ 

ushort v_state;/*vtbitmask*/ 

}; 

For each vt in use, the corresponding bit in the v state member is set. (Kernels 1.0 
through 1.1.92.) 

Release a display. 

Switch to vt argp (1 <= argp <=MAX_NR_CONSOLES). 

W ait until vt argp has been activated. 

D eallocate the memory associated with vt argp. (Since 1.1.54.) 

Se the kerna’s idea of screensize argp points to a 

struct vt_sizes { 

ushort v_rows; /*#rows*/ 

ushort v_cols;/*#columns */ 

ushort v_scrollsize; /* no longer used */ 

}; 

N ote that this does not change the video mode. Se resizecons(8). (Since 1.1.54.) 
Se the kernd’s idea of various screen parameters. argp points to a 

struct vt_consize { 

ushort v_rows; /* number of rows */ 

ushort v_cols; /* number of columns */ 

ushort v_vlin; /* number of pixel rows on screen */ 

ushort v_clin; /* number of pixel rows per character */ 

ushort v_vcol; /* number of pixd columns on screen */ 

ushort v_ccol; /* number of pixel columns per character */ 

} 
Any parameter may be set to zero, indicating no change, but if multiple parameters 
are set, they must be self-consistent. N ote that this does not change the video mode 
See resizecons(8). (Since 1.3.3.) 
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The action of the following ioctls depends on the first bytein the struct pointed to by argp, referred to here as the subcode. 
T hese are legal only for the superuser or the owner of the current tty. 


TIOCLINUX, subcode=0 Dump the screen. D isappeared in 1.1.92. (With kernd 1.1.92 or later, read from 
/dev/vesN OF /dev/vcsaNn instead.) 

TIOCLINUX, subcode=1 Get task information. D isappeared in 1.1.92. 

TIOCLINUX, subcode=2 Set sdection. argp points to a 


struct{fchar subcode short xs, ys, xe, ye: short sel mode } 


xs and ys are the starting column and row. xe and ye are the ending column and 
row. (U pper-left corner is row=column=1.) sel_mode iS @ for character-by-character 
selection, 1 for word-by-word selection, or 2 for line by-line sdection. The indicated 
screen characters are highlighted and saved in the static array se buffer in devices/ 
char/console.c. 





TIOCLINUX, subcode=3 Paste selection. The characters in the selection buffer are written to fa. 

TIOCLINUX, subcode=4 Unblank thescreen. 

TIOCLINUX, subcode=5 Sets contents of a 256-bit look up table defining characters in a “word”, for word- 
by-word selection. (Since 1.1.32.) 

TIOCLINUX, subcode=6 argp points to a char that is set to the value of the kernal variable shift state (Since 
1.1.32.) 

TIOCLINUX, subcode=7 argp points to achar that is set to the value of the kernel variable report mouse. 
(Since 1.1.33.) 

TIOCLINUX, subcode=8 Dump screen width and height, cursor position, and all the character- attribute pairs. 
(Kernels 1.1.67 through 1.1.91 only. With kernd 1.1.92 or later, read from /dev/ 
vesa* instead.) 

TIOCLINUX, subcode=9 Restore screen width and height, cursor position, and all the characte-attribute 
pairs. (Kernds 1.1.67 through 1.1.91 only. With kernel 1.1.92 or later, write to 
/dev/vcsa* instead.) 

TIOCLINUX, subcode=10 H andles the power saving feature of thenew generation of monitors. VESA screen 
blanking mode is set to argp[1], which governs what screen blanking does: 

0 Screen blanking is disabled. 
1 The current video adapter register settings are saved, then the 


controller is programmed to turn off the vertical synchronization 
pulses. T his puts the monitor into standby mode If your monitor has 
an O ff_M ode timer, then it will eventually power down by itself. 

2 The current settings are saved, then both the vertical and horizontal 
synchronization pulses are turned off. This puts the monitor into off 
mode If your monitor has no O ff_M ode timer, or if you want your 
monitor to power down immediately when the blank timer times out, 
then you choose this option. (Caution: Powering down frequently 
will damage the monitor.) (Since 1.1.76.) 


RETURN VALUES 


-1 for error, and errno is set. 


ERRORS 
errno May take on these values: 


EBADF File descriptor is invalid. 


ENOTTY File descriptor is not associated with a character special device or the specified 
request does not apply to it. 
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EINVAL File descriptor or argp is invalid. 
EPERM Permission violation. 


Do not regard this man page as documentation of the Linux console ioctls. T his is provided for the curious only, as an 
alternative to reading the source. loctls are undocumented Linux internals, liable to be changed without warning. (And 
indeed, this page more or less describes the situation as of kernel version 1.1.94; there are many minor and not-so-minor 
differences with earlier versions.) 

Very often, ioctls are introduced for communication between the kernd and one particular well-known program (fdisk, 
hdparm, setserial, tunelp, loadkeys, selection, setfont, and So on), and their behavior will be changed when required by 
this particular program. 

Programs using these ioctls will not be portable to other versions of UNIX, will not work on older versions of Linux, and 
will not work on future versions of Linux. 

Use POSIX functions. 


SEE ALSO 
kbd_mode(1), loadkeys(1), dumpkeys(1), mknod(1), setleds(1), setmetamode(1), ioperm(2), termios(2), execve(2), fent1(2), 
charsets(4), console(4), console_codes(4), mt(4), sd(4), tty(4), ttys(4), ves(4), vesa(4), mapscrn(8), setfont(8), resizecons(8), 
/usr/include/linux/kd.h, /usr/include/linux/vt.h. 


Linux, 18 September 1995 
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fd— Floppy disk device 
CONFIGURATION 


Floppy drives are block devices with major number 2. T ypically, they are owned by root. floppy (that is, user root, group 
floppy) and have either mode e66e (access checking via group membership) or mode e666 (everybody has access). The minor 
numbers encodethe devicetype, drive number, and controller number. For each device type (that is, combination of density 
and track count), there is a base minor number. To this base number, add thedrives number on its controller and 128 if the 
drive ison the secondary controller. In the following device tables, n represents the drive number. 


If you use formats with more tracks than supported by your drive, you may cause it mechanical damage T rying once if 
more tracks than the usual 40/80 are supported should not damage it, but no warranty is given for that. D on’t create 
device entries for those formats to prevent their usage if you are not sure. 


Drive independent device files that automatically detect the media format and capacity are 


EF 




















Name Base minor # 
dn t) 
5.25-inch double density device files: 
Name Capac. Cy. Sect. H eads Base minor # 
dnd360 360K 40 9 2 4 
5.25-inch high density device files: 
Name Capac. Cy. Sect. H eads Base minor # 
dnh360 360K 40 9 2 20 
dnh410 410K 41 10 2 48 
dnh420 420K 42 10 2 64 
dnh720 720K 80 9 2 24 
dnh880 880K 80 11 2 80 
dnhi200 1200K 80 la) 2 8 
dnh1440 1440K 80 18 2 40 
dnhi476 1476K 82 18 2 56 
dnh1494 1494K 83 18 2 72 
dnh1600 1600K 80 20 2 92 
3.5-inch double density device files: 
ame Capac. Cy. Sect. H eads Base minor # 
dnD360 360K 80 9 1 12 
dnD720 720K 80 9 2 16 
dnD800 800K 80 10 2 120 
dnD1040 1040K 80 13 2 84 
dnD1120 1120K 80 14 2 88 
3.5-inch high density device files: 
Name Capac. Cy. Sect. H eads Base minor # 
dnH360 360K 40 9 2 12 
dnH720 720K 80 9 2 16 
dnH820 820K 82 10 2 52 
dnH830 830K 83 10 2 68 
dnH1440 1440K 80 18 2 28 
dnH1600 1600K 80 20 2 124 
dnH1680 1680K 80 21 2 44 
dnH1722 1722K 82 21 2 60 
dnH1743 1743K 83 21 2 76 
dnH1760 1760K 80 22 2 96 
dnH1840 1840K 80 23 2 116 
dnH1920 1920K 80 24 2 100 
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3.5-inch extra density device files: 








Name Capac. Cy. Sect. H eads Base minor # 

dnE2880 2880K 80 36 2 32 

dnCompaa 2880K 80 36 2 36 

dnE3200 3200K 80 40 2 104 

dnE3520 3520K 80 44 2 108 

dnE3840 3840K 80 48 2 112 

DESCRIPTION 
d special files access the floppy disk drives in raw mode. The following ioct1(2) calls are supported by fa devices: 


FDCLRPRM Clears the media information of a drive (geometry of disk in drive). 
FDSETPRM sets the media information of adrive The media information will be lost when the media is changed. 


FDDEFPRM sets the media information of a drive (geometry of disk in drive). The media information will not be lost when the 
media is changed. T his will disable autodetection. In order to reenable autodetection, you have to issue an FDCLRPRM. 


DGETDRVTYP displays the type of a drive (name parameter). For formats that work in several drive types, FDGETDRVTYP returns a 
ame that is appropriate for the oldest drive type that supports this format. 


DFLUSH invalidates the buffer cache for the given drive 
DFLUSH invalidates the buffer cache for the given drive 


DSETMAXERRS sets the error thresholds for reporting errors, aborting the operation, recalibrating, resetting, and reading sector 
y sector. 


DSETMAXERRS gets the current error thresholds. 
DGETDRVTYP gets the internal name of the drive. 
DWERRORCLR Clears the write error statistics. 


DWERRORGET reads the write error statistics. T hese include the total number of write errors, the location and disk of the first 
write error, and the location and disk of the last write error. Disks are identified by a ganeration number that is incremented 
t (almost) each disk change. 


DTWADDLE switches the drive motor off for a few microseconds. This might be needed in order to access a disk whose sectors 
re too close togethe. 


DSETDRVPRM sets various drive parameters. 

DGETDRVPRM reads these parameters back. 

DGETDRVSTAT gets the cached drive state (disk changed, write protected et al.) 
DPOLLDRVSTAT polls the drive and return its state. 

DGETFDCSTAT gets the floppy controller state 

DRESET resets the floppy controller under certain conditions. 

DRAWwcMD Sends a raw command to the floppy controller. 
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For more precise information, consult also the <linux/fd.h> and <inux/fdreg.h>include files, as well as the manual page for 
floppy control. 


NOTES 


The various formats allow you to read and write many types of disks. H owever, if a floppy is formatted with atoo small 
intersector gap, performance may drop, up to needing a few seconds to access an entire track. To prevent this, use interleaved 
formats. It isnot possible to read floppies that are formatted using GCR (group code recording), which is used by Apple II 
and M acintosh computers (800K disks). Reading floppies that are hard sectored (one hole per sector, with the index hole 
being alittle skewed) isnot supported. T his used to be common with older 8-inch floppies. 


ma 


FILES 


/dev/fd* 


AUTHORS 


Alain Knaff (alain. Knaff@imag.fr), David Niemi (nienidc@clark.net), Bill Broadhurst (bbroad@netcom.com). 


SEE ALSO 


floppycontrol(1), mknod(1), chown(1), getfdprm(1), superformat(1), mount(8), setfd-prm(8) 
Linux, 29 January 1995 
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hd—M FM/IDE hard disk device 
DESCRIPTION 


hd* are block devices to access MFM /IDE hard disk drives in raw mode The master drive on the primary IDE controller 
(major device number 3) ishda; the slave drive is hdb. The master drive of the second controller (major device number 22) is 
hde and the Slave had. 


General IDE block device names have the form hax , or haxp, where x isaletter denoting the physical drive, andp isa 
number denoting the partition on that physical drive The first form, ndx, is used to address the whole drive. Partition 
numbers are assigned in the order the partitions are discovered, and only nonempty, nonextended partitions get anumbe. 

H owever, partition numbers 1-4 are given to the four partitions described in the M BR (the primary partitions), regardless of 
whether they are unused or extended. Thus, the first logical partition will behaxs. Both D O S-type partitioning and BSD - 
disk label partitioning are supported. You can have at most 63 partitions on an IDE disk. 


For example, /dev/hda refers to all of thefirst IDE drivein the system; and /dev/hdb3 refers to the third DOS primary 
partition on the second one. 





They are typically created by the following: 


mknod -m 660 /dev/hda b 3 0 
mknod -m 660 /dev/hda1 b 3 1 
mknod -m 660 /dev/hda2 b 3 2 


mknod 


-m 660 /dev/hda8 b 3 8 
mknod -m 660 /dev/hdb b 3 64 
mknod -m 66@ /dev/hdb1 b 3 65 
mknod -m 660 /dev/hdb2 b 3 66 


mknod -m 660 /dev/hdb8 b 3 72 
chown root.disk /dev/hd* 


FILES 


/dev/hd* 


SEE ALSO 
mknod(1), chown(1), mount(8), sa(4) 
Linux, 17 D cenber 1992 
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ispell— Format of ispeli dictionaries and affix files 


DESCRIPTION 


ispel1(1) requires two files to define the language that it is spell checking. T he first file is a dictionary containing words for 
the language, and the second is an affix file that defines he meaning of special flagsin the dictionary. T he two files are 
combined by buildhash (See spel1(1)) and written to a hash file that is not described here. 


A raw ispell dictionary (ather the main dictionary or your own personal dictionary) contains alist of words, one per line. 
Each word may optionally be followed by a slash (/) and one or more flags, which modify the root word as explained later. 
Depending on the options with which ispe11 was built, case may or may not be significant in either the root word or the 
flags, independently. Specifically, if the compile-time option caPITALIZATION is defined, case is significant in the root word; if 
not, case is ignored in the root word. If the compile-time option masksits is set to a value of 32, case is ignored in the flags; 
otherwise, case is significant in the flags. Contact your system administrator or ispe11 maintainer for more information (or 
use the -vv flag to find out). The dictionary should be sorted with the -+ flag of sort(1) before the hash file is built; thisis 
done automatically by unchlist(1), which is the normal way of building dictionaries. 


If the dictionary contains words that have string characters (see the affix file documentation, following), they must be 
written in the format given by the defstringtype statenent in the affix file This will be the case for most non-English 
languages. Be careful to use this format, rather than that of your favorite formatter, when adding words to a dictionary. If 
you add words to your personal dictionary during an ispe11 session, they will automatically be converted to the correct 
format. This feature can be used to convert an entire dictionary if necessary: 


echo qqqqq > dummy.dict 

buildhash dummy.dict affix-file dummy.hash 

awk 'fprint "*"gENDfprint "#"g' old-dict-file \ 
| ispell -a -T old-dict-string-type \ 

-d ./dummy.hash -p ./new-dict-file \ 

> /dev/null 

rm dummy. * 


The case of the root word controls the case of words accepted by ispe11, as follows: 


1. If the root word appears only in lowercase (for example, bob), it will be accepted in lowercase, capitalized, or all capitals. 

2. If the root word appears capitalized (for example Robe), it will not be accepted in all lowercase, but will be accepted 
capitalized or all in capitals. 

3. If the root word appears all in capitals (for example, UNIX), it will only be accepted all in capitals. 

4. |f theroot word appears with a “funny” capitalization (for example IT Corp), aword will be accepted only if it follows 
that capitalization, or if it appears all in capitals. 

5. Morethan one capitalization of a root word may appear in thedictionary. Flags from different capitalizations are 
combined using or. 


Redundant capitalizations (for example, bob and Bob) will be combined by buildhash and by ispe11 (for personal dictionar- 
ies), and can be removed from a raw dictionary by munchiist. 


For example, the dictionary 


bob 
Robert 
UNIX 
ITcorp 
ITCorp 


will accept bob, Bob, BOB, Robert, ROBERT, UNIX, ITcorp, ITCorp, and 1TcorP, and will reject all others. Some of the unacceptable 
forms are bob, robert, Unix, aNd ItCorp. 


ispall 


As mentioned, root words in any dictionary may be extended by flags. Each flag is a single alphabetic character, which 
represents a prefix or suffix that may be added to the root to form anew word. For example, in an English dictionary thep 
flag can be added to bathe to make bathed. Because flags are represented asa single bit in the hashed dictionary, this results 
in significant space savings. The munchlist script will reduce an existing raw dictionary by adding flags when possible 

W hen aword is extended with an affix, the affix will be acceoted only if it appears in the same case as the initial (prefix) or 
final (suffix) letter of the word. Thus, for example, the entry unrx/m in the main dictionary (M means add an apostrophe and 
an sto make a possessive) would accept UN1IX’S but would r@ect UN IX’s. If UNIX’sis legal, it must appear as a separate 
dictionary entry, and it will not be combined by munch1ist. (In general, you don’t need to worry about these things; 
munchlist guarantees that its output dictionary will accept the same set of wordsas its input, so all you have to do is add 
words to the dictionary and occasionally run munchlist to reduceits size) 

As mentioned, the affix definition file describes the affixes associated with particular flags. It also describes the character set 
used by the language. 

Although the affix-definition grammar is designed for aline-oriented layout, it is actually a free-format grammar and can be 
laid out weirdly if you want. Comments are started by a pound (sharp) sign (#), and continueto the end of theline 
Backslashes are supported in the usual fashion (\nnn, plus specials \n, \r, \t, \v, \f, \b, and the new hex format \xnn). Any 
character with special meaning to the parser can be changed to an uninterpreted token by backslashing it; for example, you 
can declare a flag named asterisk OF colon with flag n*: or flagn::. 

The grammar will be presented in a top-down fashion, with discussion of each denent. An affix-definition file must contain 
exactly one table 


table :[headers ][prefixes ][suffixes ] 


At least one of prefixes and suffixes is required. T hey can appear in either order. 

headers :[options ] char-sets 

The headers describe options global to this dictionary and language. T hese include the character sets to be used and the 
formatter, and the defaults for certain ispell flags. 


options : { fmtr-stmt | opt-stmt | flag-stmt | num-stmt } 


The options statements define the defaults for certain ispe11 flags and for the character sets used by the formatters. 
fmtr-stmt : { nroff-stmt | tex-stmt } 
A fmtr-stmt statement describes characters that have special meaning to a formatter. N ormally, this statement is not 


necessary, but some languages may have preempted the usual defaults for use as language specific characters. In this case, 
these statements may be used to redefine the special characters expected by the formatter. 


nroff-stmt : { nroffchars | troffchars } string 
The nroffchars statenent allows redefinition of certain nroff control characters. The string given must be exactly five 


characters long, and must list substitutions for the left and right parentheses, the period, the backslash, and the asterisk. (The 
right parenthesis is not currently used, but is included for completeness.) For example, the statement: 


nroffchars {}.\\* 

would replace the left and right parentheses with left and right curly braces for purposes of parsing nroff/troff strings, with 
no effect on the others (admittedly a contrived example). N ote that the backslash is escaped with a backslash. 

tex-stmt : { TeXchars | texchars } string 

The Texchars sttatenent allows redefinition of certain T eX/LaT eX control characters. T he string given must be exactly 
thirteen characters long, and must list substitutions for the left and right parentheses, the left and right square brackets, the 


left and right curly braces, the left and right angle brackets, the backslash, the dollar sign, the asterisk, the period or dot, and 
the percent sign. For example the statement: 


texchars ()\[]<\><\>\\$*.% 
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would replace the functions of the left and right curly braces with the left and right angle brackets for purposes of parsing 
T eX/LaT eX constructs, while retaining their functions for the tib bibliographic preprocessor. N ote that the backslash, the 


left square bracket, 


opt-stmt 
cmpnd- stmt 


: { cmpn 


and the right angle bracket must be escaped with a backslash. 
-stmt | aff-stmt } 


: Compoundwords compound- opt 


aff-stmt : allaffixes on-or-off 
on-or-off : { on | off } 
compound-opt : { on-or-off | controlled character } 


An opt-stmt, used 


in the preceding code, controls certain ispe11 defaults that are best made language-specific. T he 


allaffixes statement controls the default for the -p and -m options to ispell. If allaffixes isturned off (the default), ispe11 
will default to the behavior of the -P flag: root/affix suggestions will only be made if there are no “near misses.” If allaffixes 


is turned on, ispel 


The compoundwords 
default), ispe1 wi 


will default to the behavior of the -m flag: root/affix suggestions will always be made. 
statement controls the default for the -8 and -c options to ispe11. If compoundwords is turned off (the 





| default to the behavior of the -B flag: run-together words will be reported as errors. If compoundwords is 


turned on, ispe11 will default to the behavior of the -c flag: run-together words will be considered as compoundsif both are 
in the dictionary. This is useful for languages such as German and N orwegian, which form large numbers of compound 
words. Finally, if compoundwords is set to controlled, only words marked with the flag indicated by character (which should 
not be otherwise used) will be allowed to participate in compound formation. Because this option requires the flags to be 
specified in the dictionary, it is not available from the command line 


flag-stmt : flagmarker character 


The flagmarker statement describes the character that is used to separate affix flags from the root word in a raw dictionary 
file. This must be a character that is not found in any word (including in string characters; see following). T he default is / 
because this character is not normally used to represent special characters in any language. 


num-stmt : compoundmin digit 


The compoundmin statement controls the length of the two components of a compound word. This only has an effect if 
compoundwords is turned on or if the-C flag is given to ispell. [In that case, only words at least as long as the given minimum 
will be accepted as components of a compound. T he default is 3 characters. 


char-sets : norm-sets [ alt-sets ] 


The character-set section describes the characters that can be part of aword, and defines their collating order. T here must 
always be a definition of “normal” character sets; in addition, there may be one or more partial definitions of “alternate” sets 
that are used with various text formatters. 


norm-sets :[deftype ] charset-group 


A “normal” character set may optionally begin with a definition of the file suffixes that make use of this set. Following this 
are one or more character-set declarations. 


deftype : defstringtype name deformatter suffix* 


The defstringtype declaration gives a list of file suffixes that should make use of the default string characters defined as part of 
the base character set; it is only necessary if string characters are being defined. Thename parameter is astring giving the 
unique name associated with these suffixes; often it is a formatter name. If the formatter isa member of the trort family, 
nroff should be used for the name associated with the most popular macro package members of the T eX family should use 
tex. O ther names may be chosen freely, but they should be kept simple, as they are used in ispe11’s -T switch to specify a 
formatter type. The deformatter parameter specifies the deformatting style to use when processing files with the given 
suffixes. Currently, this must be either tex or nroff. The suffix parameters are a whitespace-separated list of strings which, if 
present at the end of a filename indicate that the associated set of string characters should be used by default for this file. For 
example, the suffix list for the trott family typically includes suffixes such as .ms, .me, .mm, and so on. 


charset-group : { char-stmt | string-stmt | dup-stmt }* 


A char-stmt describes single characters; a string-stmt describes characters that must appear together as a string, and which 
usually represent a single character in the target language. Either may also describe conversion between uppercase and 
lowercase A dup-stmt isused to describe alternate forms of string characters, so that a single dictionary may be used with 
several formatting programs that use different conventions for representing non-ASCII characters. 
char-stmt : wordchars character-range 
H wordchars | owercase-range uppercase-range 
; boundarychars character-range 
: boundarychars | owercase-range uppercase-range 
string-stmt : stringchar string 
I stringchar | owercase-string uppercase-string 


Characters described with the boundarychars statement are considered part of a word only if they appear singly, enbedded 
between characters declared with the wordchars Or stringchar Statements. For example if the hyphen is a boundary character 
(useful in French), the string foo-bar would bea single word, but -foo would bethe same as foo, and foo-bar would betwo 
words separated by nonword characters. 


If two ranges or strings are given in achar-stmt OF string-stmt, the first describes characters that are interpreted as lowercase 
and the second describes uppercase. In the case of astringchar statement, the two strings must be of the same length. Also, 
in astringchar statement, the actual strings may contain both uppercase and characters themselves without difficulty; for 
instance, the statement: 


stringchar "\\*(sS" "\\*(Ss" 
is legal and will not interfere with (or be interfered with by) other declarations of "s" and "s" as lowercase and uppercase, 
respectively. 


A final note on string characters: some languages collate certain special characters as if they were strings. For example, the 
German “aumlaut” is traditionally sorted as if it were ae. ispe1l isnot capable of this; each character must be treated as an 
individual entity. So in certain cases, ispe11 will sort alist of words into a different order than the standard “dictionary” 
order for the target language. 


alt-sets : alttype [ alt-stmt*] 


Because different formatters use different notations to represent non-ASCII characters, ispell must be aware of the represen- 
tations used by these formatters. T hese are declared as alternate sets of string characters. 





alttype : altstringtype name suffix* 


Thealtstringtype statement introduces each set by declaring the associated formatter name and filename suffix list. This 
nameand list are interpreted exactly asin thedefstringtype statement. Following this header are one or more alt -stmts that 
declare the alternate string characters used by this formatter. 


alt-stmt : altstringchar alt-string std-string 


The altstringchar statement describes alternate representations for string characters. For example, the -mm macro package 
of troff represents the German “a-umlaut” as a\*:, while T eX uses the sequence \ "a. If the troff versions are declared as the 
standard versions using stringchar, the T eX versions may be declared as alternates by using the statement: 


altstringchar \\\"a a\\* 


When the altstringchar statement is used to specify alternate forms, all forms for a particular formatter must be declared 
together asa group. Also, each formatter or macro package must provide a complete set of characters, both uppercase and 
lowercase, and the character sequences used for each formatter must be completely distinct. Character sequences that 
describe uppercase and lowercase versions of the same printable character must also be the same length. It may be necessary 
to define somenew macros for a given formatter to satisfy these restrictions. (The current version of buildhash does not 
enforce these restrictions, but failure to obey them may result in errors being introduced into files that are processed with 
ispell.) 


An important minor point is that ispe11 assumes that all characters declared aS wordchars OF boundarychars will Occupy 
exactly one position on the teminal screen. 
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A single character-set statement can declare dther a single character or a contiguous range of characters. A range is given asin 
egrep and the shall: [a-z] means lowercase alphabetics; [*a-z] meansall but lowercase, and so on. All character-set state- 
ments are combined (unioned) to produce the final list of characters that may be part of aword. T he collating order of the 
characters is defined by the order of their declaration; if a range is used, the characters are considered to have been declared in 
ASCII order. Characters that have case are collated next to each other, with the uppercase character first. 


The character-declaration statenents have a rather strange behavior caused by the need to match each lowercase character 
with its uppercase equivalent. In any given wordchars OF boundarychars statement, the characters in each range are first sorted 
into ASCII collating sequence, then matched one-for-one with the other range. (T he two ranges must have the same number 
of characters). Thus, for example the two statements: 


wordchars [aeiou] [AEIOU] 
wordchars [aeiou] [UOIEA] 


would produce exactly the same effect. T o get the vowels to match up “wrong,” you would have to use separate statenents: 


wordchars a U 
wordchars e 0 
wordchars i I 
wordchars o E 
wordchars u A 


which would cause uppercase e to be 0, and lowercase 0 to bee This should normally be a problem only with languages that 
have been forced to use a strange ASCII collating sequence. If your uppercase and lowercase letters both collate in the same 
order, you shouldn't have to worry about this “feature.” 


The prefixes and suffixes sections have exactly the same syntax, except for the introductory keyword: 


prefixes : prefixes flagdef* 
suffixes : suffixes flagdef* 
flagdef : flag [*jU] char : repl * 


A prefix or suffix table consists of an introductory keyword and alist of flag definitions. Flags can be defined more than once, 
in which case the definitions are combined. Each flag controls one or more repis (replacements), which are conditionally 
applied to the beginnings or endings of various words. 


Flags are named by asingle characte char. D epending on a configuration option, this character can be either any uppercase 
letter (the default configuration) or any 7-bit ASCII character. M ost languages should be able to get along with just 26 flags. 


A flag character may be prefixed with oneor more option characters. (If you wish to use one of the option characters as a flag 
character, simply encloseit in double quotes.) 


T he asterisk (*) option means that this flag participates in cross product formation. T his only matters if the file contains both 
prefix and suffix tables. If so, all prefixes and suffixes marked with an asterisk will be applied in all cross-combinations to the 
root word. For example, consider the root fix with prefixes pre and in, and suffixes es and ed. If all flags controlling these 
prefixes and suffixes are marked with an asterisk, then the single root fix would also generate prefix, prefixes, prefixed, infix, 
infixes, infixed, fix, fixes, and fixed. C ross-product formation can produce a large number of words quickly, some of which 
may beillegal, so watch out. If cross-products produce illegal words, munch1ist will not produce those flag combinations, and 
the flag will not be useful. 


repl : condition* > [ - strip-string , ] append-string 
The ~ option specifies that the associated flag is only active when a compound word is being formed. T his is useful in a 
language like G eman, in which the form of a word sometimes changes inside acompound. 


A rep1 isaconditional rule for modifying a root word. U p to eight conditions may be specified. If the conditions are 
satisfied, the rules on the rightside of the rep1 are applied, as follows: 


1. If astrip-string is given, it isfirst stripped from the beginning or ending (as appropriate) of the root word. 
2. The append-string is added at that point. 


For example, the condition . means “any word”, and the condition y means “any word ending in Y.” The following (suffix) 
replacements: 

. > MENT 

Y > -Y,IES 

would change induce to inducement and fly to flies. (If they were controlled by the same flag, they would also change fly to 
flyment, which might not be what was wanted. munchlist can be used to protect against this sort of problem; see the 
command sequence given in the next paragraph.) 

No matter how much you might want it, the strings on the right must be strings of specific characters, not ranges. The 
reasons are rooted deeply in the way ispe11 works, and it would be difficult or impossible to provide for more flexibility. For 
example, you might want to write: 


[EY] > -[EY], IES 


This will not work. Instead, you must use two separate rules: 

E > -E, IES 

Y > -Y,IES 

The application of repis can be restricted to certain words with conditions: 

condition : { . | character | range } 

A condition is a restriction on the characters that adjoin, and/or are replaced by, the right-hand side of the rep1. Up to 
eight conditions may be given, which should be enough context for anyone. The right-hand side will be applied only 

if the conditionsin the rep1 are satisfied. T he conditions also implicitly define alength; roots shorter than the number of 
conditions will not pass the test. (Asa special case, a condition of a single dot defines a length of zero, so that the rule applies 
to all words indiscriminately.) This length is independent of the separate test that insists that all flags produce an output 
word length of at least four. 


Conditions that are single characters should be separated by whitespace. For example, to specify words ending inED, write 
this: 

E D> -ED,ING # As in covered > covering 

If you write this: 

ED > -ED, ING 


the effect will be the same as 
[ED] > -ED,ING 


Asafinal, minor but important point, it is sometimes useful to rebuild a dictionary file using an incompatible suffix file. For 
example, suppose you expand ther flag to generate “er” and “ers” (thus making the z flag somewhat obsolete). To build a 
new dictionary newdict that using new affixes will accept exactly the same list of words asthe old list olddict did using old 
affixes, the -c switch of munchlist is useful, asin the following example: 


$ munchlist -c oldaffixes -1 newaffixes olddict > newdict 


If you use this procedure, your new dictionary will always accept the same list theoriginal did, even if you badly screwed up 
the affix file This is because munchlist Compares the words generated by a flag with the original word list and refuses to use 
any flags that generate illegal words. (D on’t forget that the munchlist step takes along time and eats up temporary file space.) 


EXAMPLES 
Asan example of conditional suffixes, here is the specification of thes flag from the English affix file 


flag *S: 

[°AEIOU]Y > -Y,IES # As in imply > implies 
[AEIOU]Y > S # As in convey > conveys 
[SXZH] > ES # As in fix > fixes 

[°SXZHY] > S #As in bat > bats 
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The first line applies to words ending in Y but not in vowel-Y. T he second takes care of the vowel-Y words. T he third then 
handles those words that end in a sibilant or near-sibilant, and the last picks up everything dse. 


N ote that the conditions are written very carefully so that they apply to disjoint sets of words. In particular, note that the 
fourth line excludes words ending in Y as well asthe obvious SXZH . Otherwise, it would convet “imply” into “implys.” 


Although the English affix file does not do so, you can also have a flag generate more than one variation on a root word. For 
example, you could extend the English r flag as follows: 
flag *R: 

E > R #As in skate > skater 

E > RS # As in skate > skaters 

[°AEIOU]Y > -Y,IER # As in multiply > multiplier 
[°AEIOU]Y > -Y,IERS # As in multiply > multipliers 
[AEIOU]Y > ER # As in convey > conveyer 

[AEIOU]Y > ERS # As in convey > conveyers 

[°EY] > ER # As in build > builder 

[°EY] > ERS # As in build > builders 


This flag would generate both “skater” and “skaters” from “skate.” T his capability can be very useful in languages that make 
use of noun, verb, and adjective endings. For instance, one could definea single flag that generated all the German “weak” 
verb endings. 


SEE ALSO 
ispell(1) 


Local 


Ip 


ip— Line printer devices. 


SYNOPSIS 


#include <linux/1p.h> 


CONFIGURATION 


1p[02] are character devices for the paralld line printers; they have major number 6 and minor number 02. The minor 
numbers correspond to the printer port base addresses 0x03bc, 0x0378, and 0x0278. U sually, they have mode 220 and are 
owned by root and group 1p. You can use printer ports either with polling or with interrupts. Interrupts are recommended 
when high traffic is expected, such as for laser printers. For usual dot matrix printers, polling will usually be enough. T he 
default is polling. 


DESCRIPTION 
The following ioct1(2) calls are supported: 


int ioctl(int fd, LPTIME, int arg) Sets the amount of time that the driver sleeps before rechecking the 
printer when the printer's buffer appears to be filled to arg. If you havea 
fast printer, decrease this numbe;; if you havea slow printer, then 
increase it. T hisisin hundredths of a second; the default 2 is 0.05 
seconds. It only influences the polling driver. 

int ioctl(int fd, LPCHAR, int arg) Sets the maximum number of busy-wait iterations that the polling driver 
does while waiting for the printer to get ready for receiving a character to 
arg. If printing istoo dow, increase this numbe;; if the system gets too 
slow, decrease this numbe~. T he default is 1000. It only influences the 
polling driver. 


men, kmem, port 











int ioctl(int fd, LPABORT, int arg) If arg iso, the printer driver will retry on errors, otherwise, it will abort. 
The default is 0. 

int ioctl(int fd, LPABORTOPEN, int arg) If arg iS@, open(2) will be aborted on error; otherwise, the error will be 
ignored. T he default is to ignoreit. 

int ioctl(int fd, LPCAREFUL, int arg) If arg ise, then the out-of-paper, offline and error signals are required to 
be false on all writes, otherwise they are ignored. T he default is to ignore 
them. 

int ioctl(int fd, LPWAIT, int arg) Sets the number of busy-wait iterations to wait before strobing the printer 


to accept ajust-written character and the number of iterations to wait 
before turning the strobe off again to arg. T he specification says this time 
should be 0.5 microseconds, but experience has shown the dday caused 
by the code is already enough. For that reason, thedefault valueiso. This 
is used for both the polling and the interrupt driver. 

int ioctl(int fd, LPSETIRQ, int arg) This ioct1() requires superuser privileges. It takes an int containing the 
new IRQ as argument. As aside effect, the printer is reset. When arg iso, 
the polling driver will be used, which is also default. 


int ioctl(int fd, LPGETIRQ, int *arg) Stores the currently used IRQ in arg. 

int ioctl(int fd, LPGETSTATUS, int *arg) Stores the value of the status port in arg. T he bits have the following 
meaning: 

LP_PBUSY Inverted busy input, active high 

LP_PACK Unchanged acknowledge input, active low 

LP_POUTPA Unchanged out-of-paper input, active high 

LP_PSELECD Unchanged selected input, active high 

LP_PERRORP Unchanged error input, active low 


Refer to your printer: manual for the meaning of the signal's. N ote that 
undocumented bits can also be set, depending on your printer. 


int ioctl(int fd, LPRESET) Resets the printer. No argument is used. 


FILES 


/dev/1p* 


AUTHORS 


The printer driver was originally written by Jim Weigand and Linus T orvalds. It was further improved by M ichad K. 
Johnson. The interrupt code was written by Niga Gamble. Alan Cox modularized it. LPcAREFUL, LPABORT, LPGETSTATUS Were 
added by Chris M etcalf. 


SEE ALSO 


mknod(1), chown(1), chmod(1), tune1p(8), 1pent1(8) 
15 January 1995 
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mem, kmem, port— System memory, kernd memory, and systen ports 


DESCRIPTION 


mem iS a Character device file that isan image of the main memory of the computer. It can be used, for example, to examine 
(and even patch) the system. 
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Byte addresses in mem are interpreted as physical memory addresses. References to non-existent locations cause errors to be 


returned. 


Examining and patching is likely to lead to unexpected results when read-only or write-only bits are present. 


It istypically created by 


mknod -m 660 /dev/mem c 1 1 
chown root.mem /dev/mem 


The file kmem is the same as mem, except that the kernd virtual memory rather than physical memory is accessed. 


It istypically created by 


mknod -m 640 /dev/kmem c 1 2 
chown root.mem /dev/kmem 


port issimilar to mem, but the |O ports are accessed. 


It istypically created by 


mknod -m 660 /dev/port c 1 4 
chown root.mem /dev/port 


FILES 
/dev/mem 
/dev/kmem 


/dev/port 


SEE ALSO 


mknod(1), chown(1), ioperm(2) 


Linux, 21 N ovember 1992 





mouse 
mouse— Serial mouse interface. 
CONFIG 
Serial mice are connected to a serial RS232/V 24 dialout line: see cua(4) for a description. 
DESCRIPTION 
The pinout of the usual 9 pin plug as used for serial mice is 
Pin Name U sed for 
2 RX Data 
3 TX -12 V, Imax =10 mA 
4 DTR +12 V, Imax =10 mA 
7 RTS +12 V, Imax =10 mA 
5 GND Ground 


Thisis the specification; in fact, 9 V suffices with most mice 


The mouse driver can recognize a mouse by dropping RT S to low. About 14ms later, the mouse will send 0x4D on the data 
line After a further 63ms, M icrosoft-compatible mice will send 0x33. O ther mice send different values. 


The relative mouse movement is sent as dx (positive means right) and dy (positive means down). Various mice can operate at 
different speeds. T 0 select speeds, cycle through the speeds 9600, 4800, 2400, and 1200 bits/sec, each time writing the two 
characters from the table bd ow and waiting 0.1 seconds. T he following table shows available speeds and the strings that 
select then: 





Bits/sec String 
9600 *q 
4800 *D 
2400 ¥0 
1200 *n 


The first byte of a data packet can be used to synchronization purposes. 


MICROSOFT PROTOCOL 


TheM icrosoft protocol uses 1 start bit, 7 data bits, no parity, and 1 stop bit at the speed of 1200 bits/sec. D atais sent to 
RxD in 3-byte packets. The ax and dy movements are sent as two’s-complement, 1b (rb) is set when the left (right) button is 
pressed: 





Byte d6 d5 d4 d3 d2 dl do 

1 1 Ib rb dy7 dy6 dx7 dx7 
2 0 dx5 dx4 dx3 dx2 dx1 dx0 
3 0 dy5 dy4 dy3 dy2 dyl dy0 


Original Microsoft mice have only two buttons. H oweve,, there are some three-button mice that also use the M icrosoft 
protocol. Pressing the third button is reported by sending a packet with zero movement and no buttons pressed. 


MOUSESYSTEMS PROTOCOL 


The M ouseSystems protocol uses 1 start bit, 8 data bits, no parity, and 2 stop bits at the speed of 1200 bits/sec. D ata is sent 
to RxD in 5-byte packets. dx is sent as the sum of the two two’s-complenent values, dy is send as negated sum of the two 
two’s-complanent values. 1b (mb, rb) is cleared when the left (middle, right) button is pressed: 





Byte d7 d6 d5 d4 d3 d2 dl do 
1 1 ? ? ? ? Ib mb rb 
2 0 dxa6 dxa5 dxa4 dxa3 dxa2 dxal dxa0 
3 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxb1 dxb0 
4 0 dya6 dya5 dya4 dya3 dya2 dyal dya0 
5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dyb1 dyb0 


SUN PROTOCOL 


The Sun protocol uses 1 start bit, 8 data bits, no parity, and 2 stop bits at the speed of 1200 bits/sec. D ataissent to RxD in 
3-byte packets. ax is sent as single two’s-complenent value, dy as negated two’s-complement value. 1b (mb, rb) is cleared when 
the left (middle, right) button is pressed: 





Byte d7 d6 d5 d4 d3 d2 dl do 
1 1 ? ? ? ? lb mb rb 
2 0 dx6 dx5 dx4 dx3 dx2 dxl dx0 
3 0 dy6 dy5 dy4 dy3 dy2 dyl dy0 
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MM PROTOCOL 


TheMM protocol uses 1 start bit, 8 data bits, odd parity, and 1 stop bit at the speed of 1200 bits/sec. D atais sent to RxD in 
3-byte packets. dx and dy are sent as single signed values, the sign bit indicating a negative value. 1b (mb, rb) is set when the 
left (middle, right) button is pressed: 





Byte d7 d6 d5 d4 d3 d2 dl do 
1 1 ? ? dxs dys lb mb rb 
2 0 dx6 dx5 dx4 dx3 dx2 dx1 dx0 
3 0 dy6 dy5 dy4 dy3 dy2 dyl dy0 
FILES 
/dev/mouse a commonly used symlink pointing to a mouse device 
SEE ALSO 


cua(4), bm(4) 
Linux, 10 February 1996 
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null, zero— D ata sink. 


DESCRIPTION 
D ata written on a null or zero special file is discarded. 
Reads from the nu11 special file always return end of file, whereas reads from zero always return \0 characters. 
null and zero are typically created by 


mknod -m 666 /dev/null c 1 3 
mknod -m 666 /dev/zero c 1 5 
chown root.mem /dev/null /dev/zero 


NOTES 


If these devices are not writable and readable for all users, many programs will act strangely. 
FILES 
/dev/null 
/dev/zero 
SEE ALSO 
mknod(1), chown(1) 
Linux, 21 N ovamber 1992 


ram 


ram— Ram disk device 


DESCRIPTION 
ram iS a block device to access the ram disk in raw mode. 
It istypically created by 


mknod -m 660 /dev/ram b 1 1 
chown root.disk /dev/ram 


FILES 


/dev/ram 


SEE ALSO 


mknod(1), chown(1), mount(8) 
Linux, 21 N ovamber 1992 


sd 


sd— Driver for SCSI disk drives. 
SYNOPSIS 


#include <linux/hdreg.h> 


CONFIG 


The block device name has the following form: sdip, where 1 is a letter denoting the physical drive and p isanumber 
denoting the partition on that physical drive. Often, the partition number, p, will be left off when the device corresponds to 
the whole drive 


SCSI disks have a major device number of 8 and aminor device number of the form (16 * drive number) +partition_number, 
where drive_number isthe number of the physical drive in order of detection and partition_number is as follows: 


Partition 0 The whole drive 
Partitions 1-4 TheDOS “primary” partitions 
Partitions 5-8 TheDOS “extended” (or “logical”) partitions 


For example, /dev/sda will have major 8 and minor 0 and will refer to all the first SC SI drivesin the system; /dev/sdb3 will 
have major 8 and minor 19 and will refer to the third DOS “primary” partition on thesecond SCSI drivein the system. 


At this time, only block devices are provided. Raw devices have not yet been implemented. 


DESCRIPTION 
The following ioct1s are provided: 


HDIO_REQ Returns theBlOS disk parameters in the following structure: 
struct hd geometry { 
unsigned char heads; 
unsigned char sectors; 
unsigned short cylinders; 
unsigned long start; 
}; 


A pointer to this structure is passed as the ioct1(2) parameter. 


The information returned in the parameter is the disk geometry of the 
drive as understood by DOS! This geometry is not the physical geometry 
of thedrive. It is used when constructing the drive's partition table, 
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however, and is needed for convenient operation of fdisk(1), efdisk(1), 
and 1i10(1). If the geometry information is not available zero is returned 
for all the parameters. 


BLKGETSIZE Returns the device size in sectors. The ioct1(2) parameter should bea 
pointer to a long. 

BLKRRPART Forces are-read of the SCSI disk partition tables. N o parameter is 
needed. 


The scsi(4) ioct1s are also supported. If the ioct1(2) parameter is 
required and it is NULL, then ioct1(2) will return -EINVAL. 


FILES 
/dev/sd{a-h]: T he whole device 
/dev/sd[a-h][@-8]: Individual block partitions 


SEE ALSO 
scsi(4) 
17 D ember 1992 


st 


st— SCSI tape device 
SYNOPSIS 


#include <sys/mtio.h> 

int ioctl(int fd, int request [, (void *)arg3]) 

int ioctl(int fd, MTIOCTOP, (struct mtop *)mt_cmd) 

int ioctl(int fd, MTIOCGET, (struct mtget *)mt status) 
int ioctl(int fd, MTIOCPOS, (struct mtpos *)mt_pos) 


DESCRIPTION 


The st driver provides the interface to a variety of SCSI tape devices. Currently, the driver takes control of all detected 
devices of type sequential-access. T he st driver uses major device number 9. 


Each device uses two minor device numbers: a principal minor device number, n, assigned sequentially in order of detection, 
and ano-rewind devicenumbe,, (n +128). D evices opened using the principal device number are sent a REWIND Command 
when they are closed. D evices opened using the no-rewind device number are not. O ptions such as density or block size are 
not coded in the minor device numbe. T hese options must be set by explicit ioct1() calls and remain in effect when the 
device is closed and reopened. 


Devices are typically created by 


mknod -m 660 /dev/st® c 9 0 
mknod -m 660 /dev/st1 c 9 1 
mknod -m 660 /dev/nst® c 9 128 
mknod -m 660 /dev/nst1 c 9 129 


There is no corresponding block device. The character device provides buffering and read-ahead by default and supports 
reads and writes of arbitrary size (limited by the driver's internal buffer size, which defaults to 32768 bytes but can be 
changed either by using a kernel startup option or by changing a compile-time constant). 


Device /dev/tape is usually created as a hard or soft link to the default tape device on the system. 


| 
ioctls 


The driver supports three ioct1 requests. R equests not recognized by the st driver are passed to the scsi driver. The 
definitions below are from /usr/include/1inux/mtio.h: 


utztoctop: PERFORM A TAPE OPERATION 


This request takes an argument of type (struct mtop *). N ot all drives support all operations. The driver returns an ElO 
error if the drive rejects an operation. 


/* Structure for MTIOCTOP - mag tape op command: */ 
struct mtop { 

short mt_op; /* operations defined below */ 

int mt_count; /* how many of them */ 

}; 


M agnetic tape operations: 





MTBSF Backward space over mt_count filemarks. 

MTBSFM Backward space over mt_count filenarks. Reposition the tape to the EOT 
side of the last filemark. 

MTBSR Backward space over mt_count records (tape blocks). 

MTBSS Backward space over mt_count setmarks. 

MTEOM Go to the end of the recorded media (for appending files). 

MTERASE Erase tape. 

MTFSF Forward space over mt_count filemarks. 

MTFSFM Forward space over mt_count filemarks. Reposition the tape to the BOT 
side of the last filemark. 

MTFSR Forward space over mt_count records (tape blocks). 

MTFSS Forward space over mt_count setmarks. 

MTNOP No op; flushes the driver's buffer as a side effect. Should be used before 
reading status with mT1occeT. 

MTOFFL Rewind and put the drive off line 

MTRESET Reset drive. 

MTRETEN Retention tape. 

MTREW Rewind. 

MTSEEK Seek to the tape block number specified in mt_count. This operation 
requires eather a SCSI-2 drive that supports the Locate command (device: 
specific address) or aT andberg-compatible SC SI-1 drive (T andberg, 
Archive Viper, W angtek,... ). The block number should be one that was 
previously returned by wT1ocpos because the number is device-specific. 





MTSETBLK Set the drive's block length to the value specified in mt_count. A block 
length of zero sets the drive to variable block size mode. 

MTSETDENSITY Set the tape density to the code in mt_count. Some useful density 
codes are 


18 Qx00 Implicit 0x11 QIC-525 
0x04 QIC-11 0x12 QIC-1350 

@x@5 QIC-24 0x13 DDS 

OxOF QIC-120 0x14 Exabyte EXB-8200 
Ox1@ QIC-15@ @x15 Exabyte EXB-8500 


MTWEOF W rite mt_count filanarks. 
MTWSM W rite mt_count setmarks. 


Part IV: Special Files 


MTSETDRVBUFFER 


MT_ST_BUFFER_WRITES 


MT_ST_ASYNC_WRITES 


MT_ST_READ_AHEAD 


MT_ST_TWO_EM 


MT_ST_DEBUGGING 


MT_ST_FAST_EOM 


Sé& various drive and driver options according to bits encoded in 

mt_count. T hese consist of the drive's buffering mode, six Boolean driver 
options, and the buffer write threshold. T hese parameters are initialized 
only when the device is first detected. T he settings persist when the device 
is closed and reopened. A single operation can affect just the buffering 
mode, just the Boolean options, or just the write threshold. 

A value having zeros in the high-order 4 bits will be used to set the drive's 
buffering mode. T he buffering modes are: 


) Thedrive will not report coop status on write commands until 
the data blocks are actually written to the medium. 

1 The drive may report coop status on write commands as soon 
as all the data has been transferred to the drive's internal 
buffer. 

2 The drive may report coop status on write commands as soon 


as all the data has been transferred to the drive's internal buffer 
and all buffered data from different initiators has been 
successfully written to the medium. 
To control the write threshold, the value in mt_count must include the 
constant MT_ST_WRITE_THRESHOLD logically O Red with a block count in the 
low 28 bits. The block count refers to 1024-byte blocks, not the physical 
block size on the tape. The threshold cannot exceed the driver's internal 
buffer size (see the description). 
To set and clear the Boolean options, the value in mt_count must include 
the constant mT_sT_BOOLEANS logically O Red with whatever combination 
of the following options is desired. Any options not specified are set false 
The Boolean options are 
(D efault: true) Buffer all write operations. If this option is false and the 
drive uses a fixed block size, then all write operations must be for a 
multiple of the block size This option must be set false to write reliable 
multi-volume archives. 
(D efault: true) When this options istrue, write operations return 
immediately without waiting for the data to be transferred to the drive if 
the data fits into the driver's buffer. The write threshold determines how 
full the buffer must be before a new SCSI write command is issued. Any 
errors reported by the drive will be held until the next operation. This 
option must be set false to write reliable multi-volume archives. 
(D efault: true) T his option causes the driver to provide read buffering 
and read-ahead. | f this option is false and the drive uses a fixed block size, 
then all read operations must be for a multiple of the block size. 
(D efault: false) This option modifies the driver behavior when afileis 
closed. The normal action is to write a single filemark. If the option is 
true, the driver will write two filenarks and backspace over the 
second one 
N ote that this option should not be set true for QIC tape drives because 
they are unable to overwrite a filemark. T hese drives detect the end of 
recorded data by testing for blank tape rather than two consecutive 
filemarks. 
(D efault: false) This option turns on various debugging messages from 
the driver (effective only if the driver was compiled with pesue defined). 
(D efault: false) This option causes the mTEom operation to be sent directly 
to the drive potentially speeding up the operation but causing the driver 





to lose track of the current file number normally returned by the mt1occeT 
request. If wT_sT_FAST_Eom is false, the driver will respond to an MTEOM 
request by forward spacing over files. 
Example: 
struct mtop mt_cmd; 
mt _cmd. mt_op = MTSETDRVBUFFER; 
mt _cmd. mt_count =MT_ST_BOOLEANS ; 
MT_ST_BUFFER_WRITES ! 
MT_ST_ASYNC_WRITES; 
ioctl(fd, MTIOCTOP, &mt_cmd); 


MTIOCGET: GET STATUS 
This request takes an argument of type (struct mtget *). Thedriver returns an ElO error if the drive rejects an operation. 


/* structure for MTIOCGET - mag tape get status command */ 
struct mtget { 

long mt_type; 

long mt_resid; 

/* the following registers are device dependent */ 

long mt_dsreg; 

long mt_gstat; 

long mt_erreg; 

/* The next two fields are not always used */ 

daddr_t mt_fileno; 

daddr_t mt_blkno; 
hs 
The header file defines many values for mt_type, but the current driver reports only the generic types mT_tsscs11 (Generic 
SCSI-1 tape) and mt_tsscst2 (Generic SC SI-2 tape). 
mt_resid iS always zero. (N ot implemented for SC SI tape drives.) 


mt_dsreg reports the drive's current settings for block size (in the low 24 bits) and density (in the high 8 bits). T hese fields are 
defined by mT_ST_BLKSIZE_SHIFT, MT_ST_BLKSIZE_MASK, MT_ST_DENSITY_SHIFT, aNd MT_ST_DENSITY_MASK. 


mt_gstat reports generic (device independent) status information. T he header file defines macros for testing these status bits: 








GMT_EOF (x) The tape is positioned just after a filenark (always false after an mTSEEK 
operation). 

GMT_BOT(x) The tape is positioned at the beginning of the first file (always false after 
an MTSEEK operation). 

GMT_EOT (x) A tape operation has reached the physical End of T ape 

GMT_SM(x) The tape is currently positioned at asetmark (always false after an mTSEEK 
operation). 

GMT_EOD(x) The tape is positioned at the end of recorded data. 

GMT_WR_PROT(x) The drive is write-protected. For some drives this can also mean that the 
drive does not support writing on the current medium type 

GMT_ONLINE(x) Thelast open() found the drivewith atapein place and ready for 
operation. 

GMT_D_6250(x), GMT_D_1600(x), GMT_D 800(x) This generic status information reports the current density setting for 
9-track tape drives only. 

GMT_DR_OPEN(x) The drive does not have a tape in place. 

GMT_IM_REP_EN(x) Immediate report mode (not supported). 


mt_erreg: | he only fidd defined in mt_erreg is the recovered error 
count in the low 16 bits (as defined by wT_st_SoFTERR_SHIFT and 
MT_ST_SOFTERR_MASK). D ue to inconsistencies in the way drives report 
recovered errors, this count is often not maintained. 
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MTIOCPOS: GET TAPE POSITION 


mt_fileno reports the current file number (zero-based). T his value is set to 
-1 when the file number is unknown (such as after mTBss Or MTSEEK). 
mt_b1kno reports the block number (zero-based) within the current file. 
This value is set to -1 when the block number is unknown (such as after 
MTBSF, MTBSS, OF MTSEEK), 


This request takes an argument of type (struct mtpos *) and reports the drive's notion of the current tape block number, 
which is not the same as mt_b1kno returned by mtiocceT. T his drive must bea SCSI-2 drive that supports the READ POSITION 
command (device-specific address) or a T andberg-compatible SC SI-1 drive (T andberg, Archive Viper, W angtek,... ). 


/* structure for MTIOCPOS - mag tape get position command */ 


struct mtpos { 
long mt_blkno; /* current block number */ 
}; 


RETURN VALUE 


EIO 
ENOSPC 


EACCES 


ENXIO 
EBUSY 
EOVERFLOW 


EINVAL 
ENOSYS 


COPYRIGHT 
Copyright 1995, Robert K.N ichols. 


The requested operation could not be completed. 


A write operation could not be completed because the tape reached end- 
of-medium. 


An attempt was made to write or erase a write protected tape. (This error 
isnot detected during open().) 


D uring opening, the tape device does not exist. 
The deviceis already in use or the driver was unable to allocate a buffer. 


An attempt was made to read or write a variable length block that is 
larger than the driver's internal buffer. 


An ioct1() had an illegal argument, or a requested block size was illegal. 
Unknown ioct1(). 


Permission is granted to make and distribute verbatim copies of this manual, provided the copyright notice and this 
permission notice are preserved on all copies. Additional permissions are contained in the header of the source file 


SEE ALSO 
mt(1) 


tty 


tty— Controlling terminal. 


DESCRIPTION 


Linux 1.1.86, 31 January 1995 


The file /dev/tty isa character file with major number 5 and minor number 0, usually of mode 0666 and owner.group 
root.tty. It isa synonym for the controlling terminal of a process, if any. 


In addition to the ioct1() requests supported by the device that tty refers to, the following ioct1() request is supported: 


TIOCNOTTY Detach the current process from its controlling terminal and renove it 
from its current process group, without attaching it to anew process 
group (that is, set its process group ID to zero). This ioct1() call only 
works on file descriptors connected to /dev/tty; this is used by daemon 
processes when they are invoked by a user at a terminal. T he process 
attempts to open /dev/tty; if the open succeeds, it detaches itself from the 
terminal by using T1ocnotTy, but if the open fails, it is obviously not 
attached to a terminal and does not need to detach itself. 


FILES 


/dev/tty 


SEE ALSO 


mknod(1), chown(1), getty(1), termios(2), console(4), ttys(4) 
Linux, 21 January 1992 


ttys 


ttys— Serial taminal lines. 


DESCRIPTION 
tty$[0-3] are character devices for the serial terminal lines. 
They are typically created by 


mknod -m 660 /dev/ttyS® c 4 64 # base address Ox03f8 
mknod -m 66@ /dev/ttyS1 c 4 65 # base address Ox02f8 
mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x03e8 
mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x02e8 
chown root.tty /dev/ttyS[0-3] 


FILES 


/dev/ttyS[0-3] 


SEE ALSO 


mknod(1), chown(1), getty(1), tty(4) 
Linux, 19 D cenber 1992 


VCS, VCSa 


ves, vesa— Virtual console memory. 


DESCRIPTION 


/dev/vesd isa character device with major number 7 and minor number 0, usually of mode 0644 and owner root. tty. 
It refers to the memory of the currently displayed virtual console terminal. 


/dev/ves[1-63] are character devices for virtual console terminals; they have major number 7 and minor number 1 to 63, 
usually mode 0644 and owne root.tty. /dev/vesa[0-63] are the same but include attributes and are prefixed with four bytes, 
giving the screen dimensions and cursor position: lines, columns, x, y.(x =y =o at the top-left corner of the screen.) 
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T hese replace the screendump ioct1s of console(4), so the system administrator can control access using filesystem permis- 
sions. 


The devices for the first aght virtual consoles may be created by 


for x in®@123 4567 8; do 

mknod -m 644 /dev/vcs$x c 7 $x; 

mknod -m 644 /dev/vcsa$x c 7 $[$x+128]; 
done 

chown root.tty /dev/vcs* 


N 0 iocti() requests are supported. 
EXAMPLES 


You can do a screndump on vt3 by switching to vtl and typing cat /dev/vcs3 >foo. 


This program displays the character and screen attributes under the cursor of the second virtual console and then changes the 
background color there: 


#include <unistd.h> 
#include <stdio.h> 
#include <fcntl.h> 


void main() 

{ int fd; 

struct {char lines, cols, x, y;} sern; 
char ch, attrib; 





d = open("/dev/vcsa2", O_RDWR); 

void)read(fd, &scrn, 4); 

void)lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0); 
void)read(fd, &ch, 1); 

void)read(fd, &attrib, 1); 

printf ("ch='%c' attrib=0x%@2x\n", ch, attrib); 

attrib “= 0x10; 

(void)lseek(fd, -1, 1); 

(void)write(fd, &attrib, 1); 


( 
( 
( 
( 


} 
FILES 


/dev/vcs[0-63] 
/dev/vcsa[Q-63] 


AUTHOR 


Andries Brouwer (aeb@cwi.n1) 


HISTORY 


Introduced with version 1.1.92 of the Linux kernel. 
SEE ALSO 
console(4), tty(4), ttys(4), selection(1) 
Linux, 19 February 1995 
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intro 


intro— Introduction to file formats. 


DESCRIPTION 


This chapter describes various file formats and protocols, and the used C structures, if any. 


AUTHORS 
Look at the header of the manual page for the authors and copyright conditions. N ote that these can be different from page 
to page! 
Linux, 24 July 1993 


active, active. times 


active, active.times— List of active U senet newsgroups. 


DESCRIPTION 


The file /news/1ib/active lists the newsgroups that the local site receives. Each newsgroup should be listed only once. Each 
line specifies one group; their order in the file does not matter. Within each newsgroup, articles are assigned unique names, 
which are monotonically increasing numbe’s. 

If an article is posted to newsgroups not mentioned in this file, those newsgroups are ignored. If no valid newsgroups are 
specified, the article is filed into the newsgroup “junk” and only propagated to sites that receive the “junk” newsgroup. 
Each line consists of four fields specified by aspace: 

name himark lomark flags 

The first field is the name of the newsgroup. N ewsgroups that start with the three characters to. are treated specially; see 
innd(8). The second field is the highest article number that has been used in that newsgroup. The third fied is the lowest 
article number in the group; this number is not guaranteed to be accurate and should only be taken as ahint. N ote that 
because of article cancellations, there may be gaps in the numbering sequence If the lowest article number is greater than the 
highest article number, there are no articlesin the newsgroup. T o make it possible to update an entry in-place without 
rewriting the entire file, the second and third fields are padded with leading zeros to make them a fixed width. 


The fourth field can contain one of the following flags: 


y Local postings are allowed 

n No local postings are allowed, only remote ones 

m The group is moderated and all postings must be approved 
j Articles in this group are not kept but only passed on 

x Articles cannot be posted to this newsgroup 

=fo0. bar Articles are locally filed into thefoo. bar group 


If a newsgroup has the j flag, then no articles will be filed into that newsgroup and local postings to that group should not be 
generated. If an article for such a newsgroup is received from a remote site it will be filed into the “junk” newsgroup if it is 
not cross-posted. This is different from not having a newsgroup listed in the file because sites can subscribe to j; newsgroups 
and the article will be propagated to then. 


If the fourth field of anewsgroup starts with an equal sign, then the newsgroup is an alias. Articles can be posted to the group 
but will be treated as if they were posted to the group named after the equal sign. The second and third fidds are ignored. 

N ote that the newsgroup header is not modified (Alias groups are typically used during a transition and are typically created 
with ctlinna(8)). An alias newsgroup should not point to another alias. 


adduser.conf 


The file /news/1ib/active.times provides a chronological record of when newsgroups are created. T his file isnormally 
updated by innd(8) whenever a ctlinnd newgroup command is done. Each line consist of three fidds: 


name time creator 


The first field is the name of the newsgroup. The second fidd is the time it was created, expressed as the number of seconds 
since the epoch— a time_t; S€@ gettimeofday(2). T hethird fidd is the electronic mail address of the person who created the 
group. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


ctlinna(8), inna(8) 


adduser.cont 


adduser.conf— C onfiguration file for adduser(8) and addgroup(8). 


SYNOPSIS 
/etc/adduser. conf 
DESCRIPTION 


The file adduser.conf contains defaults for the programs adduser(8) and addgroup(8). Each option takes the form option = 
value. 


The valid configuration options are 


DSHELL The login shell to be used for all new users. D efaults to /bin/bash. 

DHOME The directory in which new home directories should be created. D efaults to /home. 

SKEL The directory from which skeletal user configuration files should be copied. D efaults to / 
etc/skel. 

FIRST_UID Specifies the lowest valid UID for normal users on your system. ID s bdow FrrsT_uID are 
reserved for administrative and systen accounts. D efaults to 1000. 

USERGROUPS The usercrours variable can be either yes or no. If yes, each created user will be given their 


own group to use asa default, and ther setup will arrangeto have them create files group- 
writable by default, thus allowing them to effectively use group-writeable filespace areas 
(such as /usr/local). If no, each created user will be placed in the group whose GID is 
USERS_GID, and they will create files not group-writeable by default. 


USERS_GID If useRGRoups isno, then users_a1p isthe GID given to all newly created users. The default 
value is 100. 
FILES 
/etc/adduser.conf 
SEE ALSO 
adduser(8) 


Debian GNU /Linux version 1.94 


Part V: FileFormats 


aliases 


aliases— Aliases file for sendmail. 


SYNOPSIS 


aliases 


DESCRIPTION 
This file describes user ID aliases used by . The file resides in and is formatted as a series of lines of the form: 


name: name_l, name_2, name_3, ... 


Thename isthename to alias, and thename_n are the aliases for that name. Lines beginning with whitespace are continuation 
lines. Lines beginning with # are comments. 


Aliasing occurs only on local names. Loops cannot occur because no message will be sent to any person more than once. 


After aliasing has been done, local and valid recipients who havea . forward file in their home directory have messages 
forwarded to the list of users defined in that file. 


Thisis only the raw data file; the actual aliasing information is placed into a binary format in the files and using the program 
newaliases(1). A newaliases command should be executed each time the aliases file is changed for the change to take effect. 


SEE ALSO 


newaliases(1), dbm(3), sendmail(8), “Sendmail Installation and O peration Guide” “Sendmail: An Internetwork M ail 
Router.” 


BUGS 


Because of restrictions in dbm(3), a single alias cannot contain more than about 1000 bytes of information. You can get longer 
aliases by “chaining”— that is, making the last name in the alias a dummy name that is acontinuation alias. 


HISTORY 
The aliases file format appeared in BSD 4.0. 
BSD 4,10 May1991 


cfingerd 


cfingerd— Configurable finger daenon. 


SYNOPSIS 


cfingerd [-c;-d|-e;-0;-v] 


-¢ Check configuration 

-d Run as daemon, not inetd 

-e Emulate local finger without inetd 
-0 Turn off all finger queries 

-v Request version information 


-c checks your installed configuration. T his makes sure there are no existing errors in the current cfingerd.conf file 
-d runNS cfingerd asa daemon. Don’t run cfingerd this way if you're using inetd. 


-e allows you to emulate a local finger on a user that exists on your system. This makes it so that you can test cfingerd on 
your system before installing it. Using the -e directive is the same as installing the software, typing finger username@ and 
getting the output. Using -e username does the same. 


cfingerd 


-o turns off all finger queries. This makes it so that no one can finger your systen— no matter what they try to do. 
-v requests cfingerd version information. 


DESCRIPTION 


cfingerd isa totally new and totally configurable finger daemon— one of the first. It utilizes the finger port (port 79) to 
provide useful information on each user on your system. H owever, cfingerd provides a unique twist. 


cfingerd was designed for the sole purpose of making output on finger queries configurable | f you want to change any text 
that is displayed during finger queries, you can configure the finger daemon to display just about anything you want. 


cfingerd also takes into account any security breaches and attenpts to closethem. With .nofinger files, this is displayed 
instead of finger information, making it possible for users to keep themselves relatively anonymous from outside users. 


WHY WASIT DONE? 


The answer is simple: security. M any sites turn off finger for the reason that they don’t want outside users to see who’s on 
their system or get information about a specific user on their system. This seemed unfair to the rest of the users out there so 
this program was created. T hose sites were waiting for this type of program. M any sites that originally had their finger turned 
off turned them back on because of cfingerd. 


M any sites complained that they wanted the capability to create a fake user or a user that doesn’t exist but calls a prewritten 
shell script. cfingerd takes this into account and provides the best method possible for creating such scripts. (See 
cfingerd.conf(5) for more information on the configuration file) 


FEATURES cfingerd PROVIDES AND DESCRIPTIONS OF EACH 


cfingerd was totally rewritten. W hy is this? T he older version of cfingerd had quite a few bugs, and it didn’t quite do all the 
things that cfingerd now does. T his new version was totally revamped, and most of the bugs that were in the older version of 
cfingerd were removed in this one. T hecodeis also more compact. 


H eader and footer displays were a big part of the original rdease of cfingerd and shall continue to remain in all versions. 
H eaders and footers are only displays at the beginning and ending of all finger displays and are used as unique little 
advertisements. 


The last time displayed is always a critical issue It’s covered in cfingerd. cfingerd Smply shows how many times this user is 
connected, what ther idle timeis on each tty they're connected to, and whether they are accepting messages. If they're not 
accepting messages, a [MESG-N] display will be shown. This display also shows the last time mail was read and whether this 
user has mail. 


Stand-alone and inetd support is compiled into the program, but only ineta support is given for the time being. The reason 
is that | have not yet added the option for stand-alone daenon mode 


.nofinger files are used when a user wants to renain anonymous. T hese files should be placed in their home directories and 
can display anything they want. T here’sjust a few restrictions. T hese .nofinger display files cannot be character devices, 
directories, FIFOs, soft or hard links, or anything dse of that caliber. They must only be normal files. 


Fake users were supported for the simple fact that many sites want to create users who don’t exist and make them execute a 
shell. lf you want this done, install a fake user. Read cfingerd.cont(5) for more information on these useful options. 


Service displays were used to show what fake users you have installed on your system. T hese can be formatted however you 
want and are explained in cfingerd.conf(5). 


Searching for usernames is a powerful feature that cfingerd takes full advantage of. If you are looking for a specific username 
on the system or don’t know what ther nameis, simply use the search. username directive with cfingerd, and you can search 
for a user on your system. 


Searching for usernames is not case sensitive If you are searching for a specific username or part of the user’s name, chances 
are that it'll be displayed. 
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There's also an option to display your public PGP key if you have one. Thisis very useful if you want to keep your mail or 
othe information secret to yourself and don’t want “big brother” watching over your shoulder as you talk among yourselves. 
(Thanks to Andy Smith for this patch.) T he standard plan file is .p1an, project is .project, and PGP info is .pgpkey. 


Remember, any or all of these options stated can be turned on or off at will. If you want a specific option turned off, turn it 
off. 

ERROR MESSAGES 
Any error messages that result are fairly easy to debug if you know what to look for. 


Segmentation violations don’t always occur, but if they ever do, you can pretty easily figure out what’s going on. U nfortu- 
natdy, cfingerd doesn’t have any compatibility with older cfingerd.cont files, so if you get a segmentation violation, this 
means (usually) that your cfingerd.conf file needs to be replaced. 


Timeouts usually mean that a script has timed out or a connection to another site timed out. 


SYSLOGGING MESSAGES 


There’sno real way to describe sysLoa messages because they can be changed as the system administrator chooses. Although, 
examples can be given based on the standard configuration that was distributed. 


If any IP addresses cannot be matched to ahostname SYSLOG will display 1P: Hostname not matched. 

If the renice fails (to make the program run at the highest priority), then systoe will display Fatal - Nice died: (reason). 
If there is no buffer information is waiting in the stp1n buffer, systoe will display stbIN contains no data. 

If a trusted host fingers your site, a<- Trusted will appear. 

If a rejected host fingers your site, a<- Rejected will appear. 

If root is fingered on your site, it will display Root. 

If a service listing was fingered on your site, systoe will display Service listing. 

If a user listing was requested, sysLoe will display User listing. 

If a fake user was requested, sysLoe will display Fake user. 


If whois data was requested, sysLoe will display whois request. (N ote that whois was not implemented in this release because 
it wasn’t RFC compliant.) 


Any extra information pertaining to the incoming finger is displayed in the syslogging area. (It’s also recommended that you 
reconfigure syslog. conf(5) to display to an unused VT.) 
BUGS 


W hen data is forwarded to other sites for fingering, it shows the output of the systen that it forwarded the finger request to. 
This has got to change. 


On ELF-specific systems, services lists usually show a bit of garbage at the beginning of the finger display. T his doesn’t 
appear to be a problem on a.out systems, so if you have ELF, you might want to compile cfingerd aSa.out if thisbecomesa 
problem. 

PLANS 
Any other options or improvements will probably come from user suggestions. 
Later plans will mean you can define your own display formats for the finger display. T his means that you can redefine how 
you want your finger display to look. 

CONTACTING 


If you like the software and you want to learn more about it or want to see a feature added to it that isn’t already here, write 
to khollis@bitgate.com. 
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I've received calls at work pertaining to the software, and although | appreciate the fact that people like the software! wrote, 
I'd appreciate it if you leave me & mail and be considerate. 


cfingerd isnow being maintained by M ichael Jarvis. Any additions after cfingerd 1.2.3 should be directed toward M ichael. 
You can reach him at mjarvis@gns.com. 


If you want to see other projects that Bitgate Software is currently devdoping, check out the W eb page at http: // 
www. bitgate.com/. T his will contain all the update information on the software that is being developed and that is already 
released. 

SEE ALSO 


cfingerd.conf(5), finger(1), userlist(1), syslog.cont(5) 
cfingerd 1.2.3, 24 May 1996 


cfingerd. conf 


cfingerd.cont— Configurable finger daemon configuration file. 


SYNOPSIS 
/etc/cfingerd.conf 


DESCRIPTION 


cfingerd.conf isthe configuration file for cfingerd. T hishas bem totally rewritten to support a more readable configuration 
file. This version of the new configuration file is not compatible with the olde versions from 1.0.3 or earlier. 


Each line in the configuration file is split into three sections: FILES, CONFIG, and Hosts. Each one of those sections is split into 
subsections. 


Subtext of each option is either Boolean options, string options, or switchable options, all changeable by the systen 
administrator. 


Each section is split into a series of sections that resembles C -type definition; it’s not exact but close enough to be familiar. 
There's only one exception: T hese are not case sensitive. Any casing will do as long as the option is legal. 


Thus, each option is formatted like this: 


OPTION sub_option_name = { 

(tab/space) string option = "string format", 
(tab/space) boolean_option = [BOOL, BOOL], 
(tab/space) +/-internal_config_option 
(tab/space) host.name.here 
} 


This shows that string options are strings put into quotes, Boolean options are given as TRUE and FALSE, switchable options 
are given with the + or - directive and hostnames are used as substrings so that wildcards are not necessary. 


You can add comments using the hash mark (#) at the beginning of theline. Please note that no comments are allowed inside 
of an OPTION. 


DISPLAY FILES SECTION (FILES display files) 
Each option heeis a string option. T hese are formatted as the example shows. 
PLAN is the plan file that is used when displaying a plan. T he standard hee is . plan. 
PRouECT is the project file that is used when displaying a project description. The standard hee is . project. 
pap_KeY is the Pretty- G ood- Privacy file that is shown when displaying a public or private key. The standard here is . pgpkey. 
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(The preceding three files must be world readable but should not be world writable. This makes sure that cfingerd can read 
the file once it becomes the “nobody” UID/GID. This is generally a good idea for protection.) 


NO_FINGER is the file that is shown when a user wants to remain anonymous. T his is usually the case with root users (which 
should be standard anyway). T he standard hereis .nofinger. This file can only be a standard displayable file 


LOGFILE is the file that is used to keep logs of everything that happens to both your system and the finger program. T hese logs 
are kept as backups for your finger file and can be used to guard against attacks against your system if a finger attack occurs. 
Remember, the cfingerd.cont file is root owned, so this file should be kept in a safe hidden place. 


HEADER_DISPLAY is the file that is displayed at the top of each finger display. T he standard here is /etc/cfingerd/ 
top_finger. txt. 


FOOTER_DISPLAY is the file that is displayed at the end of each finger display. T he standard here is /etc/cfingerd/ 
bottom_finger.txt. 


NO_USER_BANNER is the file that is displayed if the user doesn’t exist. The standard here is /etc/cfingerd/nouser_banner. txt. 


NO_NAME_BANNER is the file that is displayed if no name was specified in a finger display. T his is used in conjunction with the 
SYSTEM _LIST Option (explained later). The standard here is /etc/cfingerd/noname_banner.txt. 





REJECTED_BANNER iSthefile that is displayed if a rejected host tries to finger your system for any reason. The standard here is / 
etc/cfingerd/rejected_banner.txt. 


FINGER DISPLAY CONFIGURE SECTION (CONFIG finger display) 


Each option in this section is Boolean. T he way this works is as follows: T he first Boolean option is the setting for aremote 
host or ahost that fingers you from the outside T he second Boolean option is the setting for the local host or trusted host. 
This is what people from your own system will see. 


Each option hasa - or + option. This is for user- overridable options, which will bein the next release of cfingera. T hese will 
allow users to manipulate if this information is displayed when that specific user is fingered. 


HEADER_FILE displays the header file at the beginning of each finger query. 
FOOTER FILE displays the footer file at the end of each finger query. 

LoGIN_1D displays the login ID of that particular user. 

REAL_NAME displays the real name of that particular user. 

prrREcTORY displays the user's directory. 

SHELL displays the user's shell. 

ROOM_NUMBER displays the user’s room numbe’. 

WORK_NUMBER displays the user’s work phone number. 

HOME_NUMBER displays the user’s home phone numbe. 

OTHER displays the user’s other information. 

LAST_TIME_ON displays the last time the user logged into the fingered system. 
IF_ONLINE displays whether the user is currently logged into the fingered system. 
TIME_MAIL_READ displays the last time that the fingered user read mail. 
DAY_MAIL_READ displays the last day that the fingered user read his or her mail. 
ORIGINATION displays the site from which the user logged in (if applicable). 
PLAN displays the user’s plan file. 

PROJECT displays the user's project file. 

pep displays the user's Pretty-G ood-Privacy key file. 
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REJECTED_BANNER displays the rgected banne if the site fingering your systen was in the banned-site listing. 


NO_NAME_BANNER displays the banner if no username was given. 


SYSTEM_LIST displays the system list if one was requested. 
NO_NAME displays the no-name display file if no user was selected. 


INTERNAL CONFIG CONFIGURE SECTION (CONFIG internal config) 


Each item in this section is a switchable option. T his means that a + before theitem isturned on and a - before theitem is 
turned off. 


ALLOW_MULTIPLE_FINGER_DISPLAY allows you to give a sorted output of all users on more than one specific system. This is useful 
whe you have more than one! SP machine located in different cities or even states. 


ALLOW_SEARCHABLE_FINGER allows you to let others outside your system (or within it) to search for a specific username by using 
the search.username directive, 


ALLOW_NO_IP_MATCH_FINGER allows you to let sites finger your system if a hostname could not be matched to their IP address 
successfully. 


ALLOW_USER_OVERRIDE will allow your users to override specific optionsin the FINGER DIsPLay section that you enable. 





ALLOW_USERLIST_ONLY will allow other sites that are fingering your system for a specific compiled user list to finger your system 
and get a user listing of who’s online This could bea security risk, so you might want to turn this option off if you feel it’s a 
security risk. 





ALLOW_FINGER_FORWARDING Will allow other sites to forward finger requests to a different machine if the user could not be 
located on the current machine. (In order to use this option, you must have the Hosts finger forward option set and have 
othe sites in thee) 


ALLOW_STRICT_FORMATTING makes the finger display remove all returns between display options. T his makes the finger display 
look horrible (as with GN U Finger or the other generic fingers) and makes your systen look, well, “generic.” 





ALLOW_VERBOSE_TIMESTAMPING Makes the timestamp that is displayed (at any place) very verbose. For instance where it used to 
say 
On since Sat Aug 12 03:43PM(PDT) 


would now be shown as 
On since Sat Aug 12, 1995 03:43PM(PDT) 


(Basically, ALLOW_VERBOSE_TIMESTAMPING just takes up moreroom on the display field.) 


ALLOW_NONIDENT_ACCESS lets you only allow connectionsfrom sites that run the ident daemon (or RFC 1413-compliant 
program.) T hisis for security sake and is a good measure against unknown users trying to finger your system. If this option is 
enabled, users who do not have identd running on their system (such as Windows users) will be able to finger your system. 
Systems not running identd will return unknown as the user |D and will not be permitted to finger a user on your system. 


ALLOW_FINGER_LOGGING enables cfingerd to use the LOGFILE file to store any logs of activity that happen to your system via 
finger. 


ALLOW_LINE_PARSING Makes cfingerd parse each line of every display file (including the pian, project, and pgp files) for any 
cfingerd-specific $ commands. If any are found, cfingerd will parse these commands and display correct information 
accordingly. O therwise, if thisisturned off, the display will appear without parsed commands. 


ALLOW_EXECUTION will allow users to execute scripts in place of their .plan, .project, and .pgp files. Thisis used to display the 
standard output of another program directly to the screen of the user. Keep in mind that this is a huge security risk if you 
choose to use it. It’s normally suggested that this option remain off, but you can turn it on if necessary. N evertheless, these 
programs are called as nobody. nogroup. 
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ALLOW_FAKEUSER_FINGER turns on or off the fake user option in cfingerd. If you want fake users to be defined and available to 
be fingered, you will want to enable this option. T his can be a security risk in some instances if you allow for searchable 
fingers and your script calls an execute routine on that variable. C hances are that'll never happen. 


ALLOW_USERLOG Will allow users to keep track of who has fingered than and at what time. A little file called .fingerlog will 
appear in ther directory, which they can examineto see who has fingered them. If you don’t care about this, you can disable 
it. O therwise, it’s not a bad idea. (It also logs root fingers as well.) 

SYSTEM LIST SITES CONFIGURE SECTION (CONFIG system list sites) 


This is just a series of hostnames that you want to finger when displaying your user-list display. If you have more than one 
system that you want to show, simply put ther hostname in this list, seoarated on aline by itself. 


For example, if | havea separate |SP system that I’m running on the side, say chatlink.com, | would change my configuration 
to say 


CONFIG system_list_sites = { chatlink.com, localhost } 
Remenber,, if you are listing only a couple of sites, list the sites you will want to havelisted (in order) first. The ending entry 


must bel ocal host or the finger listing will not include your site If you include! ocal host anywhere ese in the list, it will 
stop onceit has reached the! ocal host entry, so renember to list it last! 


| want to get a user listing from my own machine and from chatlink.com’s system. T his would be automatically formatted 
nicely (sorted and parsed) and would display on the screen in sorted order. This program is usually used in tandem with the 
supplied userlist(1) program. 


If no system list sites are specified, multiple system sites will not be specified. 


TRUSTED HOST SECTION (HOSTS trusted) 


Thisis a listing of the sites that you allow to finger your system exclusivey, giving them the same access that your local users 
would get. In other words, they are treated asi ocal host Users. 


Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, 2, or any 
other regex wildcard matching character will work. IP addresses will also work. H ostnames are compared case insensitive. 


REJECTED HOST SECTION (HOSTS rejected) 


This is a listing of the sites that you do not allow to finger your system. T hese sites don’t get to finger anyone (or anything 
for that matter) on your system, regardless of what they try to do. In essence, finger is cut off to that particular system. 


Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, 2, or any 
other regex wildcard matching character will work. IP addresses will also work. H ostnames are compared case insensitive. 


FORWARDED HOST SECTION (HOSTS finger forward) 


Thisis alisting of sites that are used to forward a finger query to when a finger request was processed but that particular user 
was not found on the associated system. It will step through this listing, and it will search for the user in question. If the user 
could not be found, then it will steo through to the next host and the next, until it finds one 


Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, 2, or any 
other regex wildcard matching character will work. H ostnames are compared case insensitive. 


If you do not specify any forwarding sites in this section, finger forwarding will be disabled for your system. 
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FINGER STRINGS CONFIGURE SECTION (CONFIG finger strings) 


Each option in this section isa string that can be changed to fit your needs when displaying finger information. T hese strings 
are limited to about 20 characters on the display. (If you use more than 20, the finger display will end up looking strange) 


USER_NAME is the string that is displayed when the user’s username is shown. 

REAL_NAME is the string that is displayed when the use’’s real name is shown. 

prrectory is the string that is displayed when the user's directory is shown. 

SHELL isthe string that is displayed when the user’s shall is shown. 

ROOM_NUMBER is the string that is displayed when the user’s room number is shown. 
WORK_NUMBER is the string that is displayed when the user's work phone number is shown. 
HOME_NUMBER is the string that is displayed when the user’s home phone number is shown. 
oTHER is the string that is displayed when the user's other display information is show. 

PLAN is the string that is displayed when the use’’s plan is shown. 

PRouEcT is the string that is displayed when the user’s project is shown. 

pepKeY is the string that is displayed when theuser’s PGP key is shown. 

No_PLAN is the string that is displayed when the user doesn’t havea plan file to show you. 
NO_PROJECT isthe string that is displayed when the user doesn’t havea project file to show you. 
No_pep is the string that is displayed when the user doesn’t havea PGP key file to show you. 
wart is the string that is shown when the system gathers information from other sites for a user listing. 


INTERNAL STRINGS CONFIGURE SECTION (CONFIG internal strings) 


T hese strings are changeable and can be any length you want (within reason). T hese strings are concatenated into the 
syslogging display when the appropriate finger has been issued. T his section also includes error messages that may occur. 


NO_IP_HoOsT isshown when there is no hostname that matches the incoming |P address. T his usually indicates that either the 
site didn’t register its IP address with theInterN IC or it is coming from a hacked site. 


RENICE_FATAL iS shown when the system failed to change the execution priority on the current process of cfingerd. 


STDIN_EMPTY iS shown when the input buffer on the cfingerd port is empty. (This should never really happen; it’s here for 
sanity.) 


TRUSTED_HOST is shown when a trusted host fingers your systen. If you do not specify a trusted host, cfingerd will insert 
localhost into this field. 


REJECTED_HOST is Shown when arejected host fingers your systan. If you do not specify a rejected host, cfingerd will insert 
0.0.0.0 into this field. 


ROOT_FINGER iS Shown when a use’ fingers root. 
SERVICE_FINGER iS shown when a user requests fake user services from your system. 
USER_LIST is shown when a user requests a use’ listing from your system. 
FAKE_USER iS Shown when auser fingers a fake user from your system. 
WHOIS_USER isshown when a user fingers a user with aWHOIS quay. (This option is not yet available.) 
FINGER_DENY is Shown when auser tries to finger with aforward request such aSuser @host 1@host2. | hisisnot supported 
because it could result in finger loops and a lot of traffic. 
SIGNAL STRINGS CONFIGURE SECTION (CONFIG signal strings) 


This section is used in changing the output that is given when a system crashes, or a signal is caught, and reported to the 
finger output. 
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The supported caught signals are as follows: 


SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGFPE, SIGUSR1, SIGSEGV, SIGUSR2, SIGPIPE, SIGALRM, SIGTERM, SIGCONT, 
SIGTSTP, SIGTTIN, SIGTTOU, SIGIO, SIGXCPU, SIGXFSZ, SIGVTALRM, SIGPROF, SIGWINCH 


FINGER PROGRAMS FILES SECTION (FILES finger programs) 
T hese are the programs that are called when a specific action istake on the finger display. 


FINGER is the file that is used when a use listing is requested from your machine This is used in the standard user list and in 
the sorted user list, so it is wise to use the standard here: /usr/sbin/userlist. 


wHors isthe program that isused when aWH OIS request isdoneon a specific user. 


FINGER FAKE USERS FILES SECTION (FILES finger fakeusers) 


T hese are the ever- popular fake users that you can create on your system. T hese users are ones that don’t exist (and should 
not exist, for that matter). These are, instead, treated as normal scripts that can be called for your use 


The format is as follows for fake users: 


fake_username Script_name SEARCHBOOL script 


fake_username iS thename of the fake user you want to request. M ake sure that this isa user that does not exist on your 
system. K eep in mind that if you create a fake username and that user already exists, the fake username will be shown. 


Script_name isthe standard name of your script. T his is used in the display of your services listing. 


SEARCHBOOL Specifies whether parameters can be sent to that specific fake user. If you decide to use the searcHBOOL option 
(TRUE in this case), the passed variables are 


$1 First passed option 
$2 Second passed option 
$3 Third passed option 
$4 Fourth passed option 


(If more than four options were passed to this, the request will be ignored, and an error message will be returned to the user 
who requested the finger request.) 


script isthe location of your script. It should be chmod 70@ and readable only by root. 
If you do not specify any fake users, a fake user called None will be created. This is a fake user that does nothing and calls / 
dev/null for the script. 

SERVICES HEADER CONFIGURE SECTION (CONFIG services header) 


This is the display that is given during a services finger. It should be formatted the same way that you want it to display on 
the screen. 


When specifying the finger formatted options, you should specify then asC formatted strings as wal, with the standard 
options. This should always be given last in the display. 


An example of this is 


Welcome to this system's services! 
User: Service name: Searchable: 





%-85 %-208 %-S 
Remember to keep the format string last or a staseav will result. 


SERVICES POSITIONS CONFIGURE SECTION (CONFIG services positions) 


This specifies where in the preceding display string that the information from aservicelisting isto appear. T hese numbers 
can be anywhere between 1 and 3. 


control.ctl fans | 


USER specifies the position of the username listing. 
SERVICE specifies the position of the service full- name listing. 
SEARCH Specifies the position of the Boolean search display. 


CONTACTING 


If you like this program and have questions or comments about the program’s functionality or what-have-you, write to 
khollis@bitgate.com. 


As always, | appreciate any suggestions or bug reports you might have, so bring then on! 
SEE ALSO 
cfingerd(8), cfingerd.text(5), userlist(1), finger(1), regex(3), regexp(3) 
16 May 1996 


cfingerd text rules 
EXPLANATION 


cfingerd Offers different commands that can be placed in text files to display corresponding information. Each command 
used with cfingerd in text files begins with a dollar sign ($). This usually indicates to cfingera that when it’s displaying afile 
it parses the command directly after that character. 


If you want to display araw $ sign, simply put two $ signs togethe,, or $s. 


TEXT COMMANDS 


The following is alist of text commands and what they do. Each of the text commands can be in any text case; it doesn’t 
matter. 











CENTER Displays the entire contents of the line. This command must start at the beginning of the 
line This is avery common command. 

DATE Displays the current system date in the format of MM/DD/YY. 

TIME Displays the current system timein the format HH :MM A/PM (timezone). 

IDENT Displays the identity of the current person fingering your system. 

COMPILE_DATETIME Displays the date and time of which thecurrent issue of cfingerd was compiled on your 
system. 

VERSION Displays the current version of cfingerd. 

EXEC Executes a file with x parameters after it. The $EXEC command must be on aline by itself 
in order to function properly. The command is executed as nobody.nogroup. 

SEE ALSO 


cfingerd(8), cfingerd.conf(5), finger(1), userlist(1), any of the included docs with the standard cfingerd distribution. 
cfingerd 1.2.1, 6 Jan 1996 


control.ctl 


control.ct1— Specify handling of Usenet control messages. 
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DESCRIPTION 


The file /news/1ib/control.ct1 is used to determine what action is taken when a control message is recaved. It is read by the 
parsecontrol script, which is called by all the control scripts. (For an explanation of how the control scripts are invoked, see 
innd(8).) 

The file consists of a series of lines; blank lines and lines beginning with anumber sign (#) are ignored. All other lines consist 
of four fields separated by a colon: 


messa e:from:newsgroups raction 





The first field is the name of the message for which this line is valid. It should be either the name of the control message, or 
the word aii to mean that it is valid for all messages. 


The second fidd is a shall-style pattern that matches the e mail address of the person posting the message. (T he poste’’s 
address is first converted to lowercase.) The matching is done using the shell’s case statement; see sh(1) for details. 


If the control message is newgroup OF rmgroup, then thethird fidd specifies the shell-style pattern that must match the group 
being created or removed. If the control message is of a different type, then this field is ignored. 


The fourth field specifies what action to take if this line is sd ected for the message. T he following actions are understood: 


doit Theaction requested by the control message should be performed. In most cases, the control script 
will also send mail to U senet. 
doifarg If the control message has an argument, this is treated as a doit action. If no argument was given, it 


is treated as amail entry. Thisis used in a sendsys entries script so that asite can request itsown 
newsfeeds(5) entry by posting asendsys mysite article On the other hand, sendsys bombs ask that 
the newsfeeds file be sent; if you use doifarg, such messages will not be processed automatically. 

doit=file The action is performed, but a log entry is written to the specified log file file. If file isthe word 
mail, then the record is mailed. A null string is equivalent to /dev/nu11. A pathname that starts with 
a slash is taken as the absolute filename to use as the log. All other pathnames are written to /var/ 
log/news/file.log. T he log is written by writelog (Se@ newslog(8)). 


drop N o action is taken; the message is ignored. 

log A oneline log notice is sent to standard error. innd normally directs this to thefile /var/1og/news/ 
errlog. 

log=file A log entry is written to the specified log file, fil e, which is interpreted as described previously. 

mail A mail message is sent to the news administrator. 


Lines are matched in order; the last match found in the file is the one that is used. For example, with thefollowing three 
lines: 

newgroup:*:*:drop 

newgroup: tale@*.uu.net:comp.*;misc.*;news.*;rec.*;sci.*|soc.* | talk.*:doit 

newgroup: kre@munnari.oz.au:aus.*:mail 


A newgroup coming from tale at aUUNET machine will be honored if it isin the mainstream U senet hierarchy. If kre 
posts a newgroup message creating aus. foo, then mail will be sent. All other newgroup messages are ignored. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


inna(8), newsfeeds(5), scanlogs(8) 


CVS 


evs— Concurrent Versions System support files. 


Qs 1117 


SYNOPSIS 


CVSROOT /CVSROOT/commitinfo,v 
CVSROOT /CVSROOT/cvsignore ,v 
CVSROOT /CVSROOT/cvswrappers,v 
CVSROOT /CVSROOT/editinfo,v 
CVSROOT /CVSROOT/history 
CVSROOT /CVSROOT/loginfo,v 
CVSROOT /CVSROOT/modules,v 
CVSROOT /CVSROOT/rcsinfo,v 
CVSROOT /CVSROOT/taginfo,v 


DESCRIPTION 


evs isasystem for providing source control to hierarchical collections of source directories. Commands and procedures for 
using cvs are described in cvs(1). cvs manages source repositories, the directories containing master copies of the revision- 
controlled files, by copying particular revisions of the files to (and modifications back from) developers’ private working 
directories. In terms of file structure, each individual source repository is an immediate subdirectory of scvsroor. The files 
described here are supporting files; they do not have to exist for cvs to operate, but they allow you to make cvs operation 
more flexible 





You can use the modules file to define symbolic names for collections of source maintained with evs. If thereisno modules 
file, developers must specify complete pathnames (absolute or relative to scvsroor) for the files they want to manage with cvs 
commands. You can use the commitinfo file to define programs to execute whenever cvs commit iSabout to execute. These 
programs are used for “precommit” checking to verify that the modified, added, and renoved files are really ready to be 
committed. Some uses for this check might be to turn off a portion (or all) of the source repository from a particular person 
or group or perhaps to verify that the changed files conform to the site's standards for coding practice 


You can use the cvswrappers file to record cvs wrapper commands to be used when checking files into and out of the 
repository. W rappers allow the file or directory to be processed on the way in and out of cvs. The intended uses are many; 
one possible use isto reformat a C file before the file is checked in so all the codein the repository looks the same. You can 
use the loginfo file to define programs to execute after any commit, which writes alog entry for changes in the repository. 

T hese logging programs might be used to append the log message to a file or send the log message through electronic mail to 
a group of developers. You can also post the log message to a particular newsgroup. 


You can use the taginfo file to define programsto execute after any tag or rtag Operation. T hese programs might be used to 
append a message to a file listing the new tag name and the programmer who created it, to send mail to a group of develop- 
ers, or to post a message to a particular newsgroup. You can use the rcsinfo file to define forms for log messages. You can use 
the editinfo file to define a program to execute for editing or validating cvs commit log entries. This ismost useful when used 
with a rcsinfo forms specification because it can verify that the proper fields of the form were filled in by the user commit- 
ting the change. You can use the cvsignore file to specify the default list of files to ignore during update. You can use the 
history file to record the cvs commands that affect the repository. T he creation of this file enables history logging. 


FILES 


modules The modules file records your definitions of names for collections of source code. 
evs will use these definitions if you use cvs to check in a file with the right 
format to $cvsrooT/CVSROOT/modules, v. T he modules file can contain blank lines 
and comments (lines beginning with #) as well as module definitions. Long lines 
can be continued on the next line by specifying a backslash (\) as the last 
character on theline A module definition is a single line of the modules filein 
either of two formats. In both cases, mname represents the symbolic module name 
and the remainder of the line is its definition. 
mname -a aliases ... 
This represents the simplest way of defining a module mame. T he -a flags the 
definition as a simple alias: cvs will treat any use of mname (as a command 
argument) as if the list of names aliases had been specified instead. aliases may 


Part V: FileFormats 


commitinfo, loginfo, rcsinfo, editinfo 


contain eather othe: module names or paths. When you use pathsin aliases ,cvs 
checkout Creates all intermediate directories in the working directory, just asif the 
path had been specified explicitly in the cvs arguments. 


mname [ options ] dir [ files ... ] [&module ...] 


In the simplest case, this form of module definition reduces to mame dir. This 
defines all the files in directory dir asmodule mname dir isardative path (from 
$cvsrooT) to a directory of sourcein oneof the source repositories. In this case, 
on checkout, a single directory called mame is created as a working directory; no 
intermediate directory levels are used by default, even if dir was a path involving 
several directory leveds. By explicitly specifying files in the module definition after 
dir, you can sect particular files from directory dir. T he sample definition for 
modules is an example of a module defined with a single file from a particular 
directory. H ere is another example 

m4test unsupported/gnu/m4 foreach.m4 forloop.m4 


With this definition, executing cvs checkout m4test will create a single working 
directory m4test containing the two files listed, which both come from a 
common directory several levels deep in the cvs source repository. A module 
definition can refer to other modules by including amodui e in its definition. The 
checkout Command creates a subdirectory for each such module in your working 
directory. N ew in cvs 1.3; avoid this feature if sharing module definitions with 
older versions of cvs. 


Finally, you can use one or moreof the following optionsin module definitions: 
-d name namestheworking directory something other than the module name. 
This option is new in cvs 1.3; avoid this feature if sharing module definitions 
with older versions of cvs. -i prog allows you to specify a program prog to run 
whenever files in amodule are committed. prog runs with asingle argument, the 
full pathname of the affected directory in a source repository. The commitinfo, 
loginfo, and editinfo files provide other ways to call aprogram on commit. -o 
prog allows you to specify a program prog to run whenever files in a module are 
checked out. prog runs with a single argument, the module name. -e prog allows 
you to specify a program prog to run whenever files in a module are exported. 
prog runs with asingle argument, the module name. -t prog allows you to 
specify a program prog to run whenever files in a module are tagged. prog runs 
with two arguments: the module name and the symbolic tag specified to rtag. -u 
prog allows you to specify aprogram prog to run whenever cvs update is executed 
from the top-level directory of the checked-out module. prog runswith a single 
argument, the full path to the source repository for this module. 


T hese files all specify programs to call at different points in the cvs commit 
process. They havea common structure. Each line isa pair of fields: a regular 
expression, separated by whitespace from a filename or command-line template. 
W heneve one of the regular expression matches a directory namein the 
repository, the rest of the line is used. If the line begins with a # character, the 
entire line is considered a comment and isignored. Whitespace between the 
fidds is also ignored. For loginfo, the rest of the line is acommand-line template 
to execute. T he templates can include not only a program name, but also 
whatever list of arguments you want. If you write ss somewhere on the argument 
list, cvs Supplies, at that point, the list of files affected by the commit. The first 
entry in the list is the rdative path within the source repository where the change 
is being made The renaining arguments list the files that are being modified, 
added, or removed by this commit invocation. For taginfo, the rest of the line is 
a command-line template to execute T he arguments passed to the command are, 





= 


in order, thet agname, operation (add for tag, mov for tag -F, and del for tag -d), 
and repository, and any remaining are pairs of filename revision. A nonzero exit 
of the filter program will cause the tag to be aborted. For commitinfo, the rest of 
the line is a command-line template to execute The template can include not 
only a program name but also whatever list of arguments you want. The full path 
to the current source repository is appended to the template, followed by the 
filenames of any files involved in the commit (added, removed, and modified 
files). For resinfo, therest of the line is the full path to a file that should be 
loaded into the log message template. For editinfo, the rest of thelineisa 
command-line template to execute The template can include not only a 
program name but also whatever list of arguments you want. T he full path to the 
current log message template file is appended to the tenplate. You can use one of 
two special strings instead of a regular expression: ALL specifies a command-line 
template that must always be executed, and DEFAULT specifies a command-line 
template to use if no regular expression is a match. The commitinfo file contains 
commands to execute before any other commit activity, to allow you to check 
any conditions that must be satisfied before commit can proceed. The rest of the 
commit will execute only if all sdected commands from this file exit with exit 
status 0. The rcsinfo file allows you to specify log templates for the commit 
logging session; you can use this to providea form to edit when filling out the 
commit log. The fidd after the regular expression, in this file, contains filenames 
(of files containing the logging forms) rather than command templates. T he 
editinfo file allows you to execute a script before the commit starts but after the 
log information is recorded. These “edit” scripts can verify information recorded 
in thelog file If the edit script exits with a nonzero exit status, the commit is 
aborted. The loginfo file contains commands to execute at the end of acommit. 
The text specified asa commit log message is piped through the command; 
typical uses include sending mail, filing an articlein a newsgroup, or appending 
to acentral file. 

cvsignore, .cvsignore The default list of files (or sh(1) filename patterns) to ignore during cvs update. 
At startup time cvs loadsthe compiled default list of filaaame patterns (see 
cevs(1)). Then the pe-repository list included in scvsrooT/CcVvSROOT/cvsignore iS 
loaded, if it exists. 
Then the per-user list is loaded from $HomE/.cvsignore. Finally, aS cvs traverses 
through your directories, it will load any pe-directory . cvsignore files whenever 
it finds one T hese per-directory files are only valid for exactly the directory that 
contains them, not for any subdirectories. 

history Create thisfile in $cvsroot/cvsroot to enable history logging (see the description 
of cvs history). 








SEE ALSO 
cvs(1) 


COPYING 
Copyright ° 1992, Cygnus Support, Brian Berliner, and J eff Polk. 


Permission is granted to make and distribute verbatim copies of this manual, provided the copyright notice and this 
permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
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Permission is granted to copy and distribute translations of this manual into another language, under the preceding 
conditions for modified versions, except that this permission notice may be included in translations approved by the Free 
Software F oundation instead of in the original English. 


12 February 1992 


DEVINFO 


pEvINFo— D evice entry database. 


DESCRIPTION 


DEVINFO is a text file that describes all the possible devices for a system. It is used by maKeDev(8) to create special file entries in / 
dev. It may be named either /dev/DEVINFO Or /etc/devinfo. Information about custom local devices, if any, should be placed 
iN DEVINFO. local OF /etc/devinfo. local, which has the same syntax. 


The file format is free-form. C, C-H, and shell comments are understood. T here are basically four statements: 
ignore { proc-device... } This causes the specified names to be ignored if found in /proc/devices. 


batch { device... } This creates a “batch”— acollection of devices that will all be created when the batch is 
invoked. For example, in the standard pevinro, “generic” is a batch. 

block device- spec This defines one or more block devices. 

char device-spec This defines one or more character devices. 


Hereisasampledevice-spec: 
(std, 1) { 

mem (kmem) : 1 

null (public) : 3 

core -> "/proc/kcore" 


} 


This example defines a group of devices called sta, with major number 1. Running will create all the devices in the group; 
running, for example, would make just the one device null. 


It is possible to specify, instead of just std, something like std=foo. In this case, the stuff on the right-hand side of the equals 
sign specifies aname from /proc/devices, and the major number will be retrieved from there if present. If an entry from / 
proc/devices |S specified, the explicit major number may be omitted. In this case, if the number is not found in /proc/ 
devices, attempts to create the device will be rejected. 


Inside the braces is a list of specific devices. Thename in parenthesisis the “class”; thisis something specified in mAKEDEV.cfg 
that determines the ownership and permissions of the special file created. In the preceding example, the device mem was set to 
have the class kmem, but nu11 was set to be public. Ordinarily, you’d define public to be mode 666 but kmem to be mode 660 
and owned by group kmem. Thenumber after the colon is the minor number for this particular device for instance, 3 for 
null. 


You may also specify asymbolic link with ->. For instance, core was made a link to /proc/kcore. N ote that names may 
contain any characters, but names that contain things other than alphanumerics, dash, and underscore should be put in 
double quotes. 


An entire range of devices can be created. You may specify a range of numbers in brackets: 
tty[1-8] (tty) : 1 
This creates tty1-ttys with minor device numbers starting with 1. If you specify the range in hex (prefixed by ox), the device 


names will be created numbered in hex, as is normal for ptys. T herange may appear inside the name string, but there may 
only be one range. 


expire.ctl faa] 


W hat this means is as follows: Create haa, and aight partitions on hda (hdat through haas), starting with minor number 0. 
Then create hdb, and aight partitions, starting with minor number 64. Then hac, and so on, with minor number 64*2 = 
128— and so forth. T hese are automatically placed in the class disk. T he necessary groups and batches are created so you can 
ask MAKEDEV to create hd OF hda Or hda1 and expect it to do the correct thing. 


Thereis a special syntax for creating theentire banks of devices for a hard drive: 
hd[a-d] 8/64 


N ote that simple arithmetic is permitted for specifying the minor devicenumber, as this often makes things much clearer 
and less likely to be accidentally broken. 


SEE ALSO 
MAKEDEV(8), MAKEDEV.cfg(5) 


Vergon 1.4, January 1995 


environ 


environ— User environment. 


SYNOPSIS 


extern char **environ; 


DESCRIPTION 


An array of strings called theenvironment ismade available by exec(2) when a process begins. By convention, these strings 
have the form name=val ue. Common examples are 


USER Thename of the logged-in user (used by some BSD -derived programs). 

LOGNAME Thename of the logged-in user (used by some System-V derived programs). 

HOME A user's login directory, set by login(1) from the password file passwd(5). 

LANG Thename of alocaleto use for locale categories when not overridden by Lc_ALL or more 
specific environment variables. 

PATH The sequence of directory prefixes that sh(1) and many other programs apply in searching 
for a file known by an incomplete pathname. The prefixes are separated by :. 

SHELL The filename of the user's login shell. 

TERM Theterminal type for which output is to be prepared. 


Further names maybe placed in the environment by the export command and name=val ve in sh(1) or by the setenv command 
if you use csh(1). Arguments may also be placed in the environment at the point of an exec(2). 


It is risky practice to set name=value pairs that conflict with well-known shdl variables. Setting these could cause surprising 
behavior in subshdls or system(3) commands. 


SEE ALSO 
login(1), sh(1), bash(1), csh(1), tcesh(1), exec(2), system(3) 
Linux, 21 October 1996 


expire.ctl 


expire.ct1— Control file for Usenet article expiration. 
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DESCRIPTION 
The file /news/1ib/expire.ct1 isthe default control file for the expire(8) program, which readsit at startup. Blank lines and 
lines beginning with a number sign (#) are ignored. All other lines should bein one of two formats. 


The first format specifies how long to keep a record of fully expired articles. Thisis useful when a newsfeed intermittently 
offers older news that is not kept around very long. (T he case of very old news is handled by the -c flag of inna(8).) There 
should only be one linein this format, which looks like this: 


/remember/:days 


Where days isa floating point number that specifies the upper limit to remenber a M essage ID , even if the article has 
already expired. (It does not affect article expirations.) 


M ost of the lines in the file will consist of five colon-separated fidds, as follows: 
pattern:modflag:keep:default :purge 
The pattern fidd is comma-separated set of single wildmat(3)-style patterns that specify the newsgroups to which the rest of 


the line applies. Because the file is interpreted in order, the most general patterns should be specified first, and the most 
specific patterns should be specified last. 





Themodf! ag fidd can be used to further limit newsgroups to which the line applies and should be chosen from the following 


set: 

M Only moderated groups 
Only unmoderated groups 

A All groups 


The next three fields are used to determine how long an article should be kept. Each field should be either a number of days 
(fractions such as 8.5 are allowed) or the word never. The most common useis to specify the default value for how long an 
article should be kept. The first and third fields— keep and pur ge— specify the boundaries within which an Expires header 
will be honored. T hey are ignored if an article has no Expires header. T he fields are specified in thefile as “lower-bound 
default upper-bound,” and they are explained in this order. Because most articles do not have explicit expiration dates, 
however, the second field tends to be the most important one 


Thekeep field specifies how many days an article should be kept before it will be removed. No articlein the newsgroup will 
be removed if it has been filed for less than keep days, regardless of any expiration date. If this fidd is the word never, then an 
article cannot have been kept for enough days so it will never be expired. 


Thedefauit fidd specifies how long to keep an article if no Expires header is present. If this field is the word never, then 
articles without explicit expiration dates will never be expired. 


The purge fidd specifies the upper bound on how long a article can be kept. N 0 atticle will be kept longer than the number 
of days specified by this field. All articles will be renoved after they have been kept for pur ge days. If purge is the word never, 
then the article will never be deleted. 


It is often useful to honor the expiration headers in articles, especially those in moderated groups. To do this, set keep to zero, 
default to whatever value you want, and purge to never. To ignore any Expires header, set all three fidds to the same value. 





There must be exactly oneline with apattern of * and a modflags of A; this matches all groups and is used to set the 
expiration default. It should bethe first expiration line For example: 


## How long to keep expired history 

/remember/:5 

## Most things stay for two weeks 

1A:14:14:14 

## Believe expiration dates in moderated groups, up to six weeks 
2M:1:30:42 

## Keep local stuff for a long time 

F00.*:A:30:30:30 


exports Ea 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews, 


SEE ALSO 


expire(8), wildmat(3) 


exports 


exports— NFS filesystems being exported. 
SYNOPSIS 


/etc/exports 


DESCRIPTION 


Thefile /etc/exports serves as the access control list for filesystems that can be exported to N FS clients. It is used by both the 
NFS mount daemon mountd(8) and theN FS file server daanon nfsd(8). 


The file format is similar to the SunOS exports file, except that several additional options are permitted. Each line containsa 
mount point and alist of machine or neétgroup names allowed to mount the filesystem at that point. An optional parenthe 
sized list of mount parameters may follow each machine name. Blank lines are ignored, and a# introduces a comment to the 
end of theline 


GENERAL OPTIONS 
secure This option requires that requests originate on an Internet port less than 1PpPoRT_RESERVED 
(1024). This option is on by default. To turn it off, specify insecure. 
ro Allow only read-only requests on this N FS volume. T hedefault is to allow write requests as 
well, which can also be made explicit by using the rw option. 
link_relative Convert absolute symbolic links (where the link contents start with a slash) into relative 


links by prepending the necessary number of ../sto get from the directory containing the 
link to the root on the server. This has subtle, perhaps questionable semantics when the file 
hierarchy is not mounted at its root. 


link_absolute Leave all symbolic links as they are. This is the default operation. 


USER ID MAPPING 


nfsd bases its access control to files on the server machine on the UID and GID provided in each NFS RPC request. The 
normal behavior a user would expect is that she can access her files on the server just as she would on anormal filesystem. 
This requires that the same UIDs and GID s are used on the client and the sever machine This is not always true, nor is it 
always desirable. 


Very often, it is not desirable that the root user on aclient machineis also treated as root when accessing files on the NFS 
server. To thisend, UID @ isnormally mapped to a different ID : the so-called anonymous or nobody UID. This mode of 
operation (called root squashing) is the default and can be turned off with no_root_squash. 


By default, nfsd tries to obtain the anonymous UID and GID by looking up user nobody in the password file at startup 
time If it isn’t found, aUID and GID of -2 (65534) is used. T hese values can also be overridden by the anonuia and anongid 
options. 

In addition to this, nfsa lets you specify arbitrary UIDs and GID s that should be mapped to user nobody as well. Finally, 
you can map all user requests to the anonymous UID by specifying the a11_squash option. 


For the benefit of installations where UID s differ between different machines, nfsa provides a way to dynamically map server 
UIDs to client UIDs and vice versa. Thisis enabled with the map daemon option and uses the ue1p RPC protocol. For this 
to work, you have to run the ugida(8) mapping daenon on the client host. 
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H ere's the complete list of mapping options: 


root_squash M ap requests from UID /GID 0 to the anonymous UID/GID.N ote that this does not 
apply to any other UID s that might be equally sensitive, such as user bin. 
no_root_squash Turn off root squashing. T his option is mainly useful for diskless clients. 


squash_uids and squash_gids = Thisoption specifies alist of UIDsor GIDs that should be subject to anonymous mapping. 
A valid list of ID s looks like this: 
squash_uids=0-15,20,25-50 
Usually, your squash lists will look alot simpler, such as 
squash_uids=0-100 

all_squash Map all UIDsand GID sto the anonymous use. U seful for N FS-exported public FT P 
directories, newsspool directories, and so on. The opposite option is no_al1_squash, which is 
the default setting. 

map_daemon This option turns on dynamic UID/GID mapping. Each UID in an NFS request will be 
translated to the equivalent serve UID, and each UID in an NFS reply will be mapped the 
othe way round. T his option requires that rpc.ugidd(8) runs on the client host. T he default 
setting is map_identity, which leaves all UID suntouched. T henormal squash options apply 
regardless of whether dynamic mapping is requested. 

anonuid and anongid T hese options explicitly set the UID and GID of the anonymous account. T his option is 
primarily useful for PC/N FS clients, where you might want all requests appear to be from 
oneuser. As an example consider the export entry for /home/joe in thesection “Example,” 
which maps all requests to UID 15a (which is supposedly that of user joe). 


EXAMPLE 


# sample /etc/exports file 

/ master(rw) trusty(rw,no_root_squash) 

/projects proj*.local.domain(rw) 

/usr *.local.domain(ro) @trusted(rw) 

/home/joe pc0Q1(rw,all_squash, anonuid=150, anongid=100) 
/pub (ro,insecure,all_squash) 


The first line exports the entire filesystem to machines master and trusty. In addition to write access, all UID squashing is 
turned off for host trusty. The second and third entry show examples for wildcard hostnames and netgroups (this is the 
entry @trusted). The fourth line shows the entry for the PC/N FS client discussed previously. The last line exports the public 
FTP directory to every host in the world, executing all requests under the nobody account. The insecure option in this entry 
also allows clients with N FS implementations that don’t use a reserved port for N FS. 


CAVEATS 


Unlike other N FS server implanentations, this nfsd allows you to export both adirectory and a subdirectory thereof to the 
same host, for instance usr and /usr/x11R6. In thiscase, the mount options of the most specific entry apply. For instance, 
when auser on the client host accesses a file in /usr/x11R6, the mount options given in the /usr/x11R6 entry apply. Thisis 
also true when the latter is a wildcard or netgroup entry. 


FILES 
/etc/exports Configuration file for nfsa(8) 
/etc/passwd The password file 
DIAGNOSTICS 


An error parsing the file is reported using syslogd(8) asleve notIce from a DAEMON whenever nfsd(8) Or mounta(8) is started. 
Any unknown host is reported at that time, but often not all hosts are not yet known to namea(8) at boot time, so as hosts are 
found, they are reported with the same sysloga(8) parameters. 


filesystems [| 


21 Octobe 1996 


SEE ALSO 


mountd(8), nfsd(8), nfs(5), passwd(5) 


filesystems— Linux filesystem types: minix, ext, ext2, xia, msdos, umsdos, vfat, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs. 
DESCRIPTION 


In thefile /proc/filesystems, you can find which filesystems your kernel currently supports. (If you need a currently 
unsupported one, inset the corresponding module or recompile the kernd.) 


Following is a description of the various filesystems. 


minix The filesystem used in the M inix operating system, the first to run under Linux. It has anumber 
of shortcomings: a 64M B partition sizelimit, short filenames, a single time stamp, and so on. It 
remains useful for floppies and RAM disks. 


ext An elaborate extension of the minix filesystem. It has been completely superseded by the second 
version of the extended filesystem (ext2) and will eventually be removed from the kernd. 
ext2 The high performance disk filesystem used by Linux for fixed disks as wall as removable media. 


The second extended filesystem was designed as an extension of the extended filesystem (ext). 
ext2 Offers the best performance (in terms of speed and CPU usage) of the filesystems supported 
under Linux. 

xiafs Designed and implemented to bea stable safe filesystem by extending the M inix filesystem code 
It provides the basic, most requested features without undue complexity. The xia filesystem is no 
longer activey developed or maintained. It isused infrequently. 


msdos The filesystem used by DOS, Windows, and some O S/2 computers. msdos filenames can be no 
longer than an eight-character name followed by an optional period and three-character 
extension. 

umsdos An extended D OS filesystem used by Linux. It adds capability for long filaames, UID/GID, 


POSIX permissions, and special files (devices, named pipes, and so on) unde theDOS 
filesystem, without sacrificing compatibility with DOS. 


vfat Extended DOS filesystem used by M icrosoft Windows 95 and Windows NT. vtat adds 
capability for long filaaames under the M S-D OS filesystem. 

proc A pseudo-filesystem that is used as an interface to kernel data structures rather than reading and 
interpreting /dev/kmem. In particular, its files do not take disk space. See proc(5). 

iso9660 A CD-ROM filesystem type conforming to the!SO 9660 standard. 

High Sierra Linux supports H igh Sierra, the precursor to the|SO 9660 standard for CD-ROM filesystems. It 
is automatically recognized within the isogeee filesystem support under Linux. 

Rock Ridge Linux also supports the System U se Sharing Protocol records specified by the Rock Ridge 


Interchange Protocol. T hey are used to further describe the files in the isogeeo filesysten to a 
UNIX host and provides information such aslong filenames, UID/GID, POSIX permissions, 
and devices. It is automatically recognized within the isogeee filesystem support under Linux. 


hpfs TheH igh Performance Filesystem, used in 0 S/2. This filesystem is read-only under Linux due to 
the lack of available documentation. 
sysv An implenentation of the SystemV/C oherent filesystem for Linux. It implements all X enix FS, 


SystemV /386 FS, and Coherent FS. 
nfs The network filesystem used to access disks located on remote computers. 
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smb A network filesystem that supports the SM B protocol, used by Windows for W orkgroups, 
WindowsNT, and LAN M anager. 


To use smb, you need a special mount program, which can be found in the ksmbfs package at 
ftp://sunsite.unc.edu/pub/Linux/system/Filesystems/smbfs. 


nepfs A network filesystem that supports the N CP protocol, used by N ovell N etW are 
TO use ncpfs, you need special programs found at ftp: //1inux01 .gwdg.de/pub/ncpfs. 


SEE ALSO 
proc(5), fsck(8), mkfs(8), mount(8) 
25 M arch 1996 


fstab 


fstab— Static information about the filesystems. 


SYNOPSIS 


#include <fstab.h> 


DESCRIPTION 


The file #stab contains descriptive information about the various filesystems. fstab is only read by programs and not written; 
it isthe duty of the system administrator to properly create and maintain this file Each filesystem is described on a separate 
line fidds on each line are separated by tabs or spaces. T he order of recordsin fstab is important because fsck(8), mount(8), 
and umount (8) sequentially iterate through fstab doing their thing. 


The first field (fs_spec) describes the block special device or remote filesystem to be mounted. 
Thesecond fidd (fs_file) describes the mount point for the filesystem. For swap partitions, this fidd should be specified as 


none. 


Thethird fidd (ts_vfstype) describes the type of the filesystem. T he system currently supports three types of filesystems: 











minix A local filesystem, supporting filenames of length 14 or 30 characters. 

ext A local filesystem with longer filenames and larger inodes. T his filesystem has been replaced 
by the ext2 filesystem and should no longer be used. 

ext2 A local filesystem with longer filenames, larger inodes, and a lot of other features. 

xiafs A local filesystem with longer filenames, larger inodes, and a lot of other features. 

msdos A local filesystem for M S-D OS partitions. 

hpfs A local filesystem for H PFS partitions. 

iso9660 A local filesystem used for CD-ROM drives. 

nfs A filesystem for mounting partitions from remote systems. 

swap A disk partition to be used for swapping. 


If vfs_fstype is specified as ignore, the entry is ignored. T his is useful to show disk partitions that are currently unused. 
The fourth field (fs_mntops) describes the mount options associated with the filesystem. 


It is formatted as a comma-separated list of options. It contains at least the type of mount plus any additional options 
appropriate to the filesystem type. For documentation on the available options for non-N FS file systems, see mount(8). For 
documentation on all N FS-specific options, take a look at nfs(5). Common for all types of filesystems are the options noauto 
(do not mount when mount -a iS given, such as at boot time) and user (allow a user to mount). For more details, see mount (8). 


The fifth field (fs_freq) is used for these filesystems by the dump(8) command to determine which filesystems need to be 
dumped. If the fifth field is not present, avalue of zero is returned and dump will assume that the filesystem does not need to 
be dumped. 
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Thesixth field (#s_passno) is used by the fsck(8) program to determine the order in which filesystem checks are done at 
reboot time. The root filesystem should be specified with a fs_passno of 1, and other filesystems should havea fs_passno Of 2. 
Filesystems within a drive will be checked sequentially, but filesystems on different drives will be checked at the sametime to 
utilize paralldism available in the hardware. If the sixth fidd is not present or zero, a value of zero is returned and fsck will 
assume that the filesystem does not need to be checked. 


The proper way to read records from fstab isto use the routine getmntent(3). 


FILES 
/etc/fstab 


BUGS 


The documentation in mount(8) is often more up-to-date. 


SEE ALSO 


getmntent(3), mount(8), swapon(8), nfs(5) 
HISTORY 
The fstab file format appeared in 4.0 BSD. 
Linux 0.99, 27 N ovember 1993 
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groff_font— Format of groff device and font description files. 


DESCRIPTION 
The groff_font format is roughly a superset of the ditroft font format. Unlike the ditrotr font format, there is no associated 
binary format. The font files for devicename are stored in a directory devname. T here are two types of file: a device description 
file called pesc and for each font F, a font file called F. T hese are text files; there is no associated binary format. 

DESC FILE FORMAT 
The pesc file can contain the following types of lines: 


res n There aren machine units per inch. 

hor n The horizontal resolution isn machine units. 

vert n The vertical resolution isn machine units. 

sizescale n The scale factor for point sizes. By default, this has a value of 1. O nescaled point is 


equal to one point/n. The arguments to the unitwidth and sizes commands are 
given in scaled points. 


unitwidth n Quantities in the font files are given in machine units for fonts whose point size isn 
scaled points. 

tcommand This means that the postprocessor can handle the t and u output commands. 

sizes s1 s2.... snQ This means that the device has fonts at s1, s2,... sn scaled points. The list of sizes 


must be terminated by ao. Each si can also bea range of sizesm-n. Thelist can 
extend over more than oneline 

styles S1 $2... Sm The first m font positions will be associated with styles s1... Sm. 

fonts n F1 F2 F3 ... Fn Fonts F1... Fn will be mounted in the font positionsm+1,..., m+n where misthe 
number of styles. This command may extend over more than one line A font name 
of o will cause no font to be mounted on the corresponding font position. 


Part V: FileFormats 


family fam The default font family ist am. 
charset This line and everything following in the file are ignored. It is allowed for the sake of 
backwards compatibility. 


Theres, unitwidth, fonts, and sizes lines are compulsory. O the: commands are ignored by troff but may be used by 
postprocessors to store arbitrary information about the devicein the pesc file 
FONT FILE FORMAT 


A font file has two sections. The first section is a sequence of lines, each containing a sequence of blank delimited words; the 
first word in the line is a key, and subsequent words give a value for that key. 





name F Thename of the font isr. 

spacewidth n The normal width of a space isn. 

slant n The characters of the font havea slant of n degrees. (Positive means forward.) 
ligatures ligi lig2 ... lign [0] Characters ligt, lig2,...,lign are ligatures, possible ligatures are ff, fi, f1, and ffl. 


For backwards compatibility, the list of ligatures may be terminated with ae. The 
list of ligatures may not extend over more than one line 

special The font is special; this means that when a character is requested that isnot present 
in thecurrent font, it will be searched for in any special fonts that are mounted. 


Other commands are ignored by troff but may be used by postprocessors to store arbitrary information about the font in the 
font file 


The first section can contain comments, which start with the # character and extend to the end of aline. 


The second section contains one or two subsections. It must contain a charset subsection and it may also contain a kernpairs 
subsection. These subsections can appear in any order. Each subsection starts with a word on aline by itself. 


Theword charset starts the charset subsection. The charset line is followed by a sequence of lines. Each line gives 
information for one character. A line comprises anumber of fidds separated by blanks or tabs. T he format is 


name metrics type code comment 


name identifies the character: if name isa single character c, it corresponds to the groff input character c; if it isof theform \c 
where c isasingle character, then it corresponds to the groff input character nc; otherwise it corresponds to the groff input 
character \ [name] (if it is exactly two characters xx, it can be entered as \ (xx). groff Supports aght-bit characters; however, 
some utilities have difficulties with aght-bit characters. For this reason, there isa convention that thename charn is 
equivalent to the single character whose codeisn. For example char163 is equivalent to the character with code 163, which is 
the pounds sterling sign in |SO Latin-1. Thename— is special and indicates that the character is unnamed; such characters 
can only be used by means of the \n escape sequence in troff. 


Thetype field gives the character type: 


1 The character has an descender, such asp. 
2 The character has an ascender, such as b. 
3 Thecharacter has both an ascender and a descender, such as (. 


Thecode field gives the code that the postprocessor uses to print the character. T he character can also be input to groff using 
this code by means of the \n escape sequence. T he code can be any integer. If it starts with a, it will be interpreted as octal; 
if it starts with ox or ox, it will beinterpreted as hexadecimal. 


Anything on the line after the code fidd will be ignored. 
Themetrics fidd has the form: 


width[ ,height[,depth[ ,italic_correction[,left_italic_correction 
w> [subscript _correction]]]]] 


There must not be any spaces between these subfidds. M issing subfields are assumed to beo. T he subfields are all decimal 
integers. Because there is no associated binary format, these values are not required to fit into a variable of type char as they 
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arein ditroff. Thewidth subfidds gives the width of the character. Thenhei ght subfield gives the height of the character 
(upwards is positive); if a character does not extend above the baseline, it should be given a zero height, rather than a negative 
haght. Thedeptn subfidd gives the depth of the character, that is, the distance bdow the lowest point bdow the basdine to 
which the character extends (downwards is positive); if a character does not extend below above the baseline, it should be 
given a zero depth, rather than a negative depth. Theitalic_correction subfield givesthe amount of space that should be 
added after the character when it is immediately to be followed by a character from a roman font. The 
left_italic_correction subfield gives the amount of space that should be added before the character when it is immediately 
to be preceded by acharacter from aroman font. The subscript_correction gives the amount of space that should be added 
after a character before adding a subscript. This should beless than theitalic correction. 


A line in the charset section can also have the format 


name " 





This indicates that name isjust another name for the character mentioned in the preceding line 
Theword kernpairs starts the kernpairs section. T his contains a sequence of lines of the form: 


c1 c2n 


This means that when character c1 appears next to character c2, the space between them should be increased by n. M ost 
entries in kernpairs section will have a negative value for n. 


FILES 
/usr/lib/groff/font/dev name/DESC D evice description file for device name. 
/usr/lib/groff/font/devname/F Font file for font § of device name. 

SEE ALSO 


groff_out(5), gtroff(1) 
Groff Verson 1.09, 14 February 1994 
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groff_out— groff intermediate output format. 


DESCRIPTION 


This manual page describes the format output by GNU troff. The output format used by GNU troff is very similar to that 
used by UNIX device independent troff. O nly the differences are documented here. 


The argument to the s command isin scaled points (units of points/n, wheren isthe argument to the sizescale command in 
the pesc file.) The argument to thex H aght command is also in scaled points. 


The first three output commands are guaranteed to be 


x T device 

x resn hv 

x init 

If the tcommana line is present in the pesc file troff will use the following two commands: 


KX xox iS any sequence of characters terminated by a space or anewline the first 
character should be printed at the current position, the current horizontal position 
should be increased by the width of the first character, and so on for each character. 
The width of the character is that given in the font file appropriately scaled for the 
current point size and rounded so that it is a multiple of the horizontal resolution. 
Special characters cannot be printed using this command. 


Part V: FileFormats 


un xxx This is same as the t command except that after printing each character, the current 
horizontal position is increased by the sum of the width of that character and n. 


N ote that single characters can have the eighth bit set, as can the names of fonts and special characters. 


Thenames of characters and fonts can be of arbitrary length; drivers should not assume that they will be only two characters 
long. 


When a character is to be printed, that character will always bein the current font. Unlike device-independent troff, it isnot 
necessary for drivers to search special fonts to find a character. 


T hep drawing command has been extended. T hese extensions will not be used by GN U pic if the -n option is given. 


Df n\n Se the shade of gray to be used for filling solid objects to n; n must be an integer 
between 0 and 1000, where 0 corresponds to solid white and 1000 to solid black and 
values in between correspond to intermediate shades of gray. T his applies only to 
solid circles, solid ellipses, and solid polygons. By default, alevd of 1000 will be 
used. W hatever color a solid object has, it should completely obscure everything 
beneath it. A value greater than 1000 or less than 0 can also be used: T his means fill 
with the shade of gray that is currently being used for lines and text. Normally, this 
will be black, but some drivers may provide a way of changing this. 





DC d\n D raw asolid circle with a diameter of ¢ with the leftmost point at the current 
position. 

DE dx dy\n D raw asolid ellipse with a horizontal diameter of dx and a vertical diameter of dy 
with the leftmost point at the current position. 

Dp dxl dyl dx2 dy2 ... dxn dyn\n Draw apolygon with, fori =1, ..., n +1, thei th vertex at the current position + 
Y\(dxj , dyj ). At the moment, GN U pic only uses this command to generate 
triangles and rectangles. 

DP dxl dyl dx2 dy2 ... dxn dyn\n Like Dp, but draw a solid rather than outlined polygon. 

Dt n\n Se the current line thickness to n machine units. Traditionally, UNIX troff drivers 


use a line thickness proportional to the current point size; drivers should continue to 
do this if no pt command has been given or if apt command has been given with a 
negative value of n. A zero value of n selects the smallest available line thickness. 


A difficulty arises in how the current position should be changed after the execution of these commands. T hisis not of great 
importance because the code generated by GN U pic does not depend on this. Given a drawing command of the form 


\De xl yl x2 y2 ... xm yn 


where c isnot one of c, e, |, a, or ~, UNIX troff will treat each of thexi asahorizontal quantity and each of theyi asa 
vertical quantity and will assume that the width of the drawn object is >”, xi and that the height is)... yi. (The 
assumption about the height can be seen by examining the st and sb registers afte: using such aD command in a\w escape 
sequence.) T his rule also holds for all the original drawing commands with the exception of D e For the sake of compatibil- 
ity, GNU troff also follows this rule, even though it produces an ugly result in the case of the Df, Dt, and, to a lesser extent, 
DE commands. T hus after executing aD command of the form 


Dc xl yl x2 y2 ... xm yn\n 
the current position should be increased by (Yo 7-1 xis Wi yi). 


A continuation convention permits the argument to thex X command to contain newlines: when outputting the argument 
to thex X command, GNU troff will follow each newline in the argument with a+ character (as usual, it will terminate the 
entire argument with a newline); thusif the line afte the line containing the x X command starts with +, then the newline 
ending the line containing the x X command should be treated as part of the argument to thex X command, the+ should be 
ignored, and the part of the line following the + should be treated like the part of the line following the x X command. 


history fas] 


grotf verson 1.09, 14 February 1994 


SEE ALSO 


groff_font(5) 


group 
group— U ser group file. 


DESCRIPTION 


/etc/group isan ASCII file that defines the groups to which users belong. T hereis one entry per line, and each linehas the 
format 


group_name:passwd:GlD:user list 


The field descriptions are 


group_name Thename of the group. 
passwd The (encrypted) group password. If this field isempty, no password is needed. 
GID Thenumerical group |D. 
user_list All the group member's usernames, separated by commas. 
FILES 
/etc/group 
SEE ALSO 


login(1), newgrp(1), passwd(5) 
Linux, 29 D cenber 1992 
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history— Record of current and recently expired U senet articles. 


DESCRIPTION 


Thefile /news/1ib/history keepsa record of all articles currently stored in the news system, as well as those that have been 
received but since expired. 


The file consists of text lines. Each line corresponds to one article The file is normally kept sorted in the order in which 
articles are received, although thisisnot a requirement. innd(8) appends a new line each timeit files an article and expire(8) 
builds a new version of the file by removing old articles and purging old entries. 


Each line consists of two or three fidds separated by a tab, shown beow as \t: 

<Message-|D>\t date 

<Message-|D>\t date \t files 

Themessage-10 fied is the value of the article's M essage-|D header, including the angle brackets. 

Thedate field consists of three subfields separated by a tilde All subfidds are the text representation of thenumber of 
seconds since the epoch— a time_t; Se@ gettimeofday(2). T hefirst subfidd is the article's arrival date. If copies of the article 
are still present, then the second subfield is either the value of the article's Expires header or ahyphen if no expiration date 


was specified. If an article has been expired, the second subfidd will be a hyphen. The third subfield is the value of the 
article's D ate header, recording when the article was posted. 


fz] Part V: FileFormats 


Thefiles fidd isa set of entries separated by one or more spaces. Each entry consists of the name of the newsgroup, a slash, 
and the article number. This field is empty if the article has been expired. 


For example, an article cross-posted to comp.sources.unix and comp. sources. d that was posted on February 10, 1991, (and 
received three minutes later) with an expiration date of M ay 5, 1991, could have a history line (broken into two lines for 
display) like the following: 


<312@litchi.foo.com> \t 666162000° 673329600° 666162180 
\t comp.sources.unix/1104 comp.sources.d/7056 


In addition to the text file, there is a dbz(3z) database associated with the file that uses the M essage-ID fidd asa key to 
determine the offset in the text file where the associated line begins. F or historical reasons, the key includes the trailing \o 
byte (which is not stored in the text file). 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


dbz(3z), expire(8), innd(8), news-recovery(8) 


hosts.nntp, hosts.nntp.nolimit 


hosts.nntp, hosts.nntp.nolimit— List of hosts that feed NNTP news. 


DESCRIPTION 


Thefile /news/1ib/hosts.nntp iS read by innd(8) to get the list of hosts that feed the local site Usenet news using the NNTP 
protocol. T he server reads this file at startup or when directed to by ctlinna(8). When ahosts connects to the N NTP port of 
the system on which innd isrunning, the server will do acheck to see if thar Internet address is the same as one of the hosts 
named in this file. If the host is not mentioned, then inna will spawn an nnrpa(8) to process the connection, with the 
accepted connection on standard input and standard output. 


Comments begin with a number sign (#) and continue through the end of the line. Blank lines and comments are also 
ignored. All other lines should consist of two or three fidds separated by acolon. 


The first fied should be athe an Internet address in dotted-quad format or an address that can be parsed by 
gethostbyname(3). If ahost’s entry has multiple addresses, all of them will be added to the access list. The second field, which 
may be blank, isthe password the foreign host is required to use when first connecting. The third field, which may be 
omitted, isa list of newsgroups to which the host may post articles. This list is parsed as anewsfeeds(5) subscription list; 
groups not in the list are ignored. 


Because innd is usually started at system boot time, the local nameserver may not be fully operational when inna parses this 
file As awork-around, a ctlinnd reload Command can be performed after a dday of an hour or so. It is also possibleto 
provide both ahost’s name and its dotted-quad address in the file 


For example: 


## FOO has a password, UUNET doesn't. 
## UUNET cannot post to local groups. 
## These are comment lines. 

news. foo.com: magic 
uunet.uu.net::!foo.* 


If the file contains passwords, it should not be world-readable. T he file /news/1ib/hosts.nntp.nolimit, if it exists, is read 
whenever the hosts. nntp file is read. It has the same format, although only the first field is used. Any host mentioned in this 
fileis not subject to the incoming connections limit specified by innd’s -c flag. T his can be used to allow local hosts or time. 
sensitive peers to connect regardless of the local conditions. 


hosts access [| 


HISTORY 


Written by Rich $alz (rsalze@uunet.uu.net) for InterN etN ews. 


SEE ALSO 


ctlinnd(8), innd(8), nnrpa(8) 
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hosts_access— Format of host access control files. 


DESCRIPTION 


This manual page describes a simple access control language that is based on client (hostname/address, username) and server 
(process name) patterns. Examples are given at the end. The impatient reader can skip to the “Examples” section for a quick 
introduction. 


In the following text, daemon is the process name of a network daemon process, and client is the name or address of a host 
requesting service. N etwork daemon process names are specified in the inetd configuration file. 


ACCESS CONTROL FILES 
T he access control software consults two files. The search stops at the first match: 
Access will be granted when a (daemon client ) pair matches an entry in the /etc/hosts.allow file 
Otherwise, access will be denied when a (daemon,cli ent ) pair matches an entry in the /etc/hosts.deny file 
Otherwise, access will be granted. 


A non-existing access control file is treated as if it were an empty file. T hus, access control can be turned off by providing no 
access control files. 
ACCESS CONTROL RULES 


Each access control file consists of zero or more lines of text. T hese lines are processed in order of appearance. T he search 
terminates when a match is found. 


A newline character is ignored when it is preceded by a backslash character. 
Blank lines or lines that begin with a# character are ignored. 
All other lines should satisfy the following format, things between [] being optional: 


daemon_list : client_list [ : shell_command ] 


daemon_list iSalist of one or more daemon process names (argv[0] values) or wildcards. 





client_list iSalist of one or more hostnames, host addresses, patterns, or wildcards that will be matched against the ranote 
hostname or address. 


List elements should be separated by blanks or commas. 
W ith the exception of N 1S (YP) netgroup lookups, all access control checks are case insensitive 


PATTERNS 
The access control language implenents the following patterns: 
A string that begins with a . character: A client name or address is matched if its last components match the specified 
pattern. For example, thepattern .tue.ni matches the hostnamewzv.win.tue.nl. 


A string that ends with a . character: A client name or address is matched if its first fidds match the given string. For 
example, the pattern 131.155. matches the address of (almost) every host on the Eindhoven University network 
(131.155.x.x), 


Part V: FileFormats 


A string that begins with ae character is treated as anetgroup name N etgroups are usually supported on systems with NIS 
(formerly YP) databases. A client hostname is matched if it isa (host) member of the specified netgroup. 

An expression of the form n.n.n.n/m.m.m.miSinterpreted as anet /mask pair. A client addressis matched if net is equal to the 
bitwise ano of the address and themask. For example, thenet /mask pattern 131.155.72.0/255.255.254.@ matches every address 
in the range 131.155.72.0 through 131.155.73.255. 


WILDCARDS 


The access control language supports explicit wildcards: 


ALL If this token appears in a daemon list, it matches all network daemon process names. If the ALL 
token appears in aclient list, it matches all client names and addresses. 

LOCAL M atches any string that does not contain a dot character. Typical use isin client lists. 

UNKNOWN M atches any host whose name or address are unknown. Should be used with care: H ostnames 


may be unavailable due to temporary nameserver problems. A network address will be 
unavailable when the software cannot figure out what type of network it is talking to. 

KNOWN M atches any host whose name and address are known. Should be used with care: H ostnames 
may be unavailable due to temporary nameserver problems. A network address will be 
unavailable when the software cannot figure out what type of network it is talking to. 

FAIL Like the aLL wildcard but causes the software to pretend that the scan of the current access 
control table fails. FAIL is being phased out; it will become an undocumented feature. The 
EXCEPT Operator is a much cleaner alternative. 





OPERATORS 
EXCEPT Intended useis of theform:|ist_1 EXCEPT |ist_2; thisconstruct matches anything that 
matches!ist_1 unlessit matches!ist_2.Thisconstruct can be used in daemon lists and in 
client lists. The Except operator can be nested: If the control language would permit the use 
of parentheses, a EXCEPT b EXCEPT c would parse aS (a EXCEPT (b EXCEPT c)). 
SHELL COMMANDS 
If the first-matched access control rule contains a shell command, that command is subjected to the following substitutions: 
%a Expands to the remote host address. 
%C Expands to client information: user @host, user @address, ahostname, or just an address, 


depending on how much information is available 

Expands to the remote hostname (or address, if the hostnameis unavailable). 
Expands to the daemon process name (argv[@] value). 

Expands to the daemon process !D. 

Expands to the remote username (or unknown). 

Expands to asingle% character. 
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Characters in % expansions that may confuse the shell are replaced by underscores. T he result is executed by a /bin/sh child 
process with standard input, output, and error connected to /dev/nu11. Specify an a at the end of thecommand if you do not 
want to wait until it has completed. 

Shel commands should not rely on the patH setting of the inetd. Instead, they should use absolute pathnames, or they 
should begin with an explicit PATH=what ever Statement. 


REMOTE USERNAME LOOKUP 


W hen the client host supports the RFC 931 protocol or one of its descendants (Tap, 1pENT) the wrapper programs can 
retrieve additional information about the owner of aconnection. When available, remote username information is logged 
together with the client hostname and can beused to match patternslike 


daemon list : ... user_pattern@host_pattern ... 


hosts access [| 


The daemon wrappers can be configured at compile time to perform rule-driven username lookups (default) or to always 
interrogate the client host. In the case of rule driven username lookups, the preceding rule would cause username lookup 
only when both the daemon_list and thehost_pattern match. 


A user pattern has the same syntax as a daemon process name, hostname, or host address pattern, so the same wildcards and 
so on apply (but netgroup membership of users is not supported). One should not get carried away with username lookups, 
however. 


Theremote username information cannot be trusted when it isneeded most— that is, when the remote system has been 
compromised. In general, ALL and (UN) KNowN are the only username patterns that make sense. 


Username lookups are possible only with T C P-based services and only when the client host runs a suitable daemon; in all 
other cases the result is unknown. 


A well-known U NIX kernel bug may cause loss of service when username lookups are blocked by a firewall. T he wrapper 
README document describes a procedure to find out if your kernd has this bug. 


Username lookups cause noticeable delays for PC users. The default timeout for username lookups is ten seconds: too short 
to cope with slow networks but long enough to irritate PC users. 


Sdective username lookups can alleviate the last problem. For example arule like 


daemon list : @pcnetgroup ALL@ALL 
would match members of thepcnet group without doing username lookups but would perform username lookups with all 
other systems. 

EXAMPLES 


T he language is flexible enough that different types of access control policy can be expressed with a minimum of fuss. 
Although the language uses two access control tables, the most common policies can be implemented with one of the tables 
being trivial or even enpty. 


W hen reading the following examples, it is important to realize that the allow table is scanned before the deny table that the 
search terminates when a match is found, and that access is granted when no match is found at all. 


The examples use host and domain names. T hey can be improved by including address or network/netmask information to 
reduce the impact of tenporary nameserver lookup failures. 


MOSTLY CLOSED 
In this case, access is denied by default. O nly explicitly authorized hosts are permitted access. 
T he default policy (no access) isimplenented with a trivial deny file: 
/etc/hosts.deny: 
ALL: ALL 
This denies all serviceto all hosts, unless they are permitted access by entries in the allow file 
The explicitly authorized hosts are listed in the allow file 
/etc/hosts. allow: 


ALL: LOCAL @some_net group 
ALL: .foobar.edu EXCEPT terminalserver. foobar.edu 


The first rule permits access to all servicesfrom hosts in the local domain (no . in thehostname) and from menbers of the 
some_netgroup ne@group. The second rule permits access to all services from all hosts in the . foobar.edu domain, with the 
exception of terminalserver. foobar.edu. 


MOSTLY OPEN 
H ere, access is granted by default; only explicitly specified hosts are refused service. 


Part V: FileFormats 


The default policy (access granted) makes the allow file redundant so that it can be omitted. T he explicitly non-authorized 
hosts are listed in the deny file: 


/etc/hosts.deny: 


ALL: some.host.name, .some.domain 
ALL EXCEPT in.fingerd: other.host.name, .other.domain 


The first rule denies some hosts all services; the second rule still permits finger requests from other hosts. 


BOOBY TRAPS 


Thenext example permits tftp requests from hostsin thelocal domain. Requests from any other hosts are denied. Instead of 
the requested file a finger probe is sent to the offending host. The result is mailed to the superuser. 


/etc/hosts. allow: 


in.tftpd: LOCAL, .my.domain 

/etc/hosts.deny: 

in.tftpd: ALL: (/some/where/safe_finger -1 @%h | \ 
/usr/ucb/mail -s %d-%h root) & 


The safe_finger command comes with the tcpd wrapper and should be installed in a suitable place. It limits possible damage 
from data sent by the ranote finger server. It gives better protection than the standard finger command. 


The expansion of the xh (remote host) and %d (service name) sequences is described in the section on shell commands. 
Warning: Do not booby-trap your finger daemon, unless you are prepared for infinite finger loops. 


On network firewall systems, this trick can be carried even further. The typical network firewall only provides a limited set of 
services to the outer world. All other services can be “bugged” just like the preceding tftp example. The result is an excellent 
early-warning system. 


DIAGNOSTICS 


An error is reported when a syntax error is found in a host access control rule, when the length of an access control rule 
exceeds the capacity of an internal buffer, when an access control rule is not taminated by a newline character, when the 
result of %<char acter > expansion would overflow an internal buffer, and when a system call fails that shouldn't. All problems 
are reported via the syslog daemon. 

FILES 


/etc/hosts.allow, (daemon client ) pairs that are granted access. 
/etc/hosts.deny, (daemon client ) pairs that are denied access. 


SEE ALSO 
tcpa(8), TCP/IP daenon wrapper program 

BUGS 
If anameserver lookup times out, the hostname will not be available to the access control software, even though the host is 
registered. 


Domain nameserver lookups are case insensitive, N 1S (formerly YP) netgroup lookups are case sensitive. 


AUTHOR 


W ietse V enema (wietse@wzv.win.tue.n1), Department of M athenatics and Computing Science, Eindhoven University of 
Technology, Den D olech 2, P.O. Box 513, 5600 MB Eindhoven, The N ehelands. 
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hosts options 


hosts_options— H ost access control language extensions. 


DESCRIPTION 


This document describes optional extensions to the language described in the hosts_access(5) document. T he extensions are 
enabled at program build time by editing the makefile 


T he extensible language uses the following format: 
daemon list : client_list : option : option ... 


The first two fields are described in the hosts_access(5) manual page. The ranainder of the rules is alist of zero or more 
options. Any : characters within options should be protected with a backslash. 


An option is of the form keyword Or keyword = value. Options are processed in the specified order. W ith some options, the 
value is Subjected to %<charact er > Substitutions. 


OPTIONS 
severity = mail.info Change the severity levd at which theevent will be logged. Facility names (such as 
mail) are optional and are not supported on systems with older syslog implementa 
tions. T he severity option can be used to enphasize or to completely ignore specific 
events. 
allow (deny) Grant (deny) service, even when the matched rule was found in the hosts. deny 


(hosts.allow) file T hese options must appear at the end of arule. 


W ith the allow and deny keywords, it is possible to keep all access control rules within a single file— for example, in the 
hosts.allow file: 


ALL: .friendly.domain: allow 
ALL: ALL: deny 


This permits access from specific hosts only. On the other hand, 


ALL: .trouble.makers: deny 
ALL: ALL: allow 


This permits access from all hosts except a few troublemakers. 


twist = shell_command Replace the current process by an instance of the 
specified shell command, after peforming the 
ss<char acter > expansions described in the 
hosts_access(5) Manual page. stdin, stdout, and 
stderr are connected to the remote client process. 
This option must appear at the end of arule 
Examples: 

in.ftpd : ... : twist = /bin/echo 421 Some bounce message sends a customized bounce 
message to the remote client instead of running the 
real FT P daemon. 

in.telnetd : ... : twist = PATH=/some/other; exec in.telnetd Runs /some/other/in.telnetd without polluting its 
command-line array or its process environment. 
Warning: In case of U DP services, do not twist into 
commands that use the standard I/O or the 
read(2)/write(2) routines to communicate with the 
client process; UD P requires other 1/0 primitives. 

spawn = shell command Execute the shell command in a child process, after 
performing the %<char act er > expansions described 
in the hosts_access(5) manual page. The command 
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is executed with stdin, stdout, and stderr 
connected to the null device so that it won’t mess 
up the conversation with the renote host. Example: 


spawn = (/some/where/safe_finger -1 @%h | /usr/ucb/mail root) & Executes, in a background child process, the shell 
command safe_finger -1 @%h | mail root after 
replacing sh by the name or address of the remote 
host. 


The example uses the safe_finger command 
instead of the regular finger command to limit 
possible damage from data sent by the finger server. 
The safe_finger command is part of the daemon 
wrapper package it isa wrapper around the regular 
finger command that filters the data sent by the 
remote host. 


umask = 022 Like the umask command that is built into the shel. 
An umask of 022 prevents the creation of files with 
group and world write permission. T he umask 
argument should be an octal number. 

keepalive Causes the server to periodically send a message to 
the client. The connection is considered broken 
when the client does not respond. The keepalive 
option can be useful when users turn off ther 
machine while it is still connected to a server. The 
keepalive option isnot useful for datagram (UD P) 
services. 

linger = number_of_seconds Specifies how long the kerne! will try to deliver not- 
yet delivered data after the server process closes a 
connection. 

nice = niceval 

nice (no argument) Change the nice value of the process (default 10). 
Specify a positive value to spend more C PU 
resources on other processes. 

user = nobody Assume the privileges of the nobody account. T hisis 
useful with inetd implementations that run all 
services with root privilege. It is good practice to 
run services such as finger at a reduced privilege 
leva. 

group = tty Assume the privileges of the tty group. This is 
useful mostly in combination with the user option. 
In order to switch both user and group ID s, switch 
group ID before switching user ID. 

setenv = name value Place a (name, value) pair into the process environ- 
ment. Theval ve is subjected to %<character> 
expansions and may contain whitespace (but 
leading and trailing blanks are stripped off). 
Warning: M any network daemons reset ther 
environment before spawning a login or shell 
process. 


inittab 
rfc931 = timeout_in_seconds 


rfc931 (no argument) Look up the ranote user name with the RFC 931 
(ident and so on) protocol. This option issilently 
ignored in case of services based on transports other 
than TCP. It requires that the client system runsan 
RFC 931 (ident and so on) compliant daenon and 
may cause noticeable ddays with connections from 
non-UN IX hosts. The time-out period is optional. 
If no time-out is specified, a default value is taken. 


DIAGNOSTICS 


When a syntax error is found in an access control rule, the error is reoorted to the syslog daemon; further options will be 
ignored, and service is denied. 


SEE ALSO 


hosts_access(5), the default access control language 


AUTHOR 


W ietse V enema (wietse@wzv.win.tue.n1), D epartment of M athenatics and Computing Science, Eindhoven U niversity of 
Technology, Den D olech 2, P.O. Box 513, 5600 MB Eindhoven, The N ethelands. 


inittab 
inittab— Format of the inittab file used by the SysV -compatible init process. 


DESCRIPTION 


The inittab file describes which processes are started at bootup and during normal operation (such as /etc/rc, gettys). init 
distinguishes multiple run levels, of which each can have its own set of processes that are started. Valid run! evel Sareo-6 and 
A, B, and ¢ for ondemand entries. An entry in the inittab file has the following format: 


id:runlevels saction:process 


Lines beginning with # are ignored. 


id A uniquetwo-character-sequence which identifies an entry in inittab. 
N ote: For gettys or other login processes, thei fidd should be the tty suffix of the 
corresponding tty, such as 1 for tty1. O therwise, the login accounting will not work 
correctly. Thisis a bug in login and will be fixed. 


runlevel s D escribesin which run levels the specified action should be taken. 
action Describes which action should be taken. 
process Specifies the process to be executed. If the process fidd starts with a+ character, init will 


not do utmp and wtmp accounting for that process. T hisis needed for gettys that insist on 
doing their own utmp/wtmp housekeeping. T his is also a historic bug. 


Valid actions are 


respawn The process will be restarted whenever it terminates (such as getty). 

wait The process will be started once when the specified run leva is entered and init will wait 
for its termination. 

once T he process will be executed once when the specified run levd is entered. 


boot The process will be executed during system boot. Therun level field is ignored. 
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bootwait 


otf 


ondemand 


initdefault 


sysinit 


powerwait 


powerfail 


powerokwait 


ctrlaltdel 


The process will be executed during system boot while init waits for its termination (such 
as /etc/rc). Therunievel field isignored. 


This does nothing. 


A process marked with ondemand will be executed whenever the specified ondemand run leva 
is called. However, norunievel change will occur. 


An initdefault-entry specifies the run level that should be entered after system boot. If 


noneexists, ini 
The process wi 


bootwait entries. 


The process wi 


will ask for arunl evel on the console. 


be executed during system boot. It will be executed before any boot or 


be executed when init receives the siapwr signal 


, indicating that there is 


something wrong with the power. init will wait for the process to finish before continuing. 


AS powerwait but init will not wait for the processes completion. 


The process wi 
called /etc/powe 
again. 
The process wi 











be executed when init receives the siapwr signal 


, provided thereis a file 


rstatus Containing the word ox. This means that the power has come back 


be executed when init receives the siainT signal 


. This means that someone 


on the system console pressed the CtritAlt+D a key combination. Typically, one wants to 


execute some sort of shutdown eather to get into single-user leve 





or to reboot the machine. 


Therunievel field may contain multiple characters for different run levds, such as 123 if the process should be started in run 
levels 1, 2 and 3. ondemand entries may contain ana, B, orc. Therunievel field of sysinit, boot, aNd bootwait entries are 


ignored. 


When therun leva is changed, any running processes that are not specified for the new run level are killed, first with steTERM 


and then wi 


EXAMPLES 


th SIGKILL. 


Thisis an example of an inittab that resembles the old Linux inittab: 


# inittab for linux 
id:1:initdefault: 
rc: :bootwait: /etc/rc 


1:1: respawn 
2:1:respawn 
3:1:respawn 
4:1:respawn 


:/etc/getty 9600 tty1 
:/etc/getty 9600 tty2 
:/etc/getty 9600 tty3 
:/etc/getty 9600 tty4 


This inittab file executes /etc/rc during boot and starts gettys on tty1-tty4. 


A more daborate inittab with different run leve's (see the comments inside) is 


#Level to run in 


id:4:initde 
ud: :boot:/e 
rc: :bootwai 
r::boot:/e 


level 3: 
level 4: 


we Ht Ht Ht HK HO 


mr:126:once 
mi:345:once 


ault: 
c/update 
:/ete/re 
c/crond 


level 1: getty on tty1 
level 2: getty on tty1-4 


ty1-4, dialin via modem(ttys2) 
ty1-4, ttyb 





:/usr/bin/nodialin 
:/usr/bin/dialin 


1:1234:respawn:/etc/getty 9600 tty1 
2:234:respawn:/etc/getty 9600 tty2 
3:234: respawn: /etc/getty 9600 tty3 


inn.conf 


4:234:respawn:/etc/getty 9600 tty4 
s2:3:respawn: /etc/mgetty ttys2 19200 
b:4:respawn:/etc/getty 19200L ttyb 
ca::ctrlaltdel:/etc/shutdown -t3 -rf now 


FILES 
/etc/inittab 


AUTHOR 


init was written by Miquel van Smoorenburg (miquels@drinkel.nl.mugnet.org). The manual page was written by Sebastian 
Lederer (lederer@francium. informatik.uni-bonn.de) and modified by M ichad H aardt (u31b3hs@pool. informatik.rwth- 
aachen.de). 


SEE ALSO 


init(8), telinit(8) 
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inn.conf— Configuration data for InterN etN ews programs. 


DESCRIPTION 


Thefile /news/1ib/inn.conf is used to determine various parameters. Blank lines and lines starting with anumber sign (#) are 
ignored. All other lines specify parameters that may be read and should be of the following form: 


name : [optional whitespace] value 


Everything after the whitespace and up to the end of the lineistaken as theval ve; multi-word values should not be put in 
quotes. T he case of names is significant; server isnot the same as Server Or SERVER. 


Some parameters specified in the file may be overridden by environment variables, and some file parameters may be used to 
mask real data, such as when hiding a cluster of hosts behind a single dectronic mail hostname. The current set of parameters 
is as follows: 


fromhost This is the name of the host to use when building the From header line. T he default isthe 
fully qualified domain name of the local host. The value of the FRomHosT environment 
variable, if it exists, overrides this. 

moderatormailer This names the default machine that contains forwarding aliases for all moderated groups. It 
is only used if the moderators(5) file doesn’t exist or if the group is not matched by that file 
The value is interpreted asa pattern match; see moderators(5). 





organization This specifies what to put in the O rganization header if it is blank. T he value of the 
ORGANIZATION environment variable if it exists, overrides this. 

pathhost This specifies how to namethe local site when building the Path header line T he default is 
the fully qualified domain name of the local host. 

server This specifies the name of the NNTP server to which an article should be posted. T he value 
of the nnTPSERVER environment variable, if it exists, overrides this. 

domain This should be the domain name of the local host. It should not havea leading period, and 


it should not be a full host address. It is used only if the GetFapn routinein 1ibinn(3) cannot 
get the fully qualified domain name by using either the gethostname(2) or gethostbyname(3) 
calls. The check is very simple if either routine returns a name with a period in it, then it is 
assumed to have the full domain name 
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Three parameters are used only by nnrpd when accepting postings from clients: 


mime -version 


mime -contenttype 


mime -encoding 


If this parameter is present, then nnrpd will add the necessary MIME (M ultipurpose Internet 
M ail Extensions) headers to all any articles that do not havea M ime-V ersion header. This 
parameter specifies the MIME version and should normally be 1.0. 

If MIME headers are being added, this parameter specifies the value of the Content-T ype 
header. The default value is text/plain; charset=US-ASCII. 

If MIME headers are being added, this parameter specifies the value of the Content- 

T ransfer-Encoding header. T he default value is 7bit. 


N ote that this file can be identical on all machines in an organization. 


EXAMPLE 


fromhost: 
moderatormailer: 
organization: 
#pathhost: 
server: 


domain: 


foo.com 
%s@uunet.uu.net 
Foo, Incorporated 
Use Fann. 

news. foo.com 


foo.com 


This file is intended to be fairly static; any changes made to it are typically not reflected until a program restarts. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


libinn(3), moderators(5) 


innwatch.ctl 


innwatch.ct1— C ontrol Usenet supervision by innwatch. 


DESCRIPTION 


The file /news/1ib/innwatch.ct1 is used to determine what actions are taken during the periodic supervisions by innwatch. 


The file consists of a series of lines; blank lines and lines beginning with anumber sign (#) are ignored. All other lines consist 
of seven fidds, each preceded by a delimiting character: 


:label:state: condition: test: limit: command: reason 


The delimiter can be any one of several non-alphanumeric characters that does not appear elsewhere in the line there is no 
way to quote it to include it in any of the fields. Any of !, ,, :, @, ;, or? isa good choice Each line can havea different 
ddimiter; the first character on each lineis the delimiter for that line Whitespace surrounding ddimiters, except before the 
first, isignored and does not form part of thefields, whitespace within fields is permitted. All delimiters must be present. 





The first field is alabe for the control line It is used as an internal state indicator and in ctlinnd messages to control the 


server. If omitted, the line number is used. 


The second fidd specifies when this control line should be used. It consists of a list of labels and special indicators separated 
by whitespace. If the current state matches against any of the labd's in this field, this line will be used as described below. The 


values that may be used are 





2 This line matches if the current state is the same as the label on this line or if the current state 
iSrun, the initial state. T his is also the default state if this fidd is empty. 





innwatch.ctl 


+ This line matches if the current state is run. 

* This line always matches. 

label This line matches if the current state is the specified | abel . 
-label This line matches if the current state is not the specified | abel. 


The third fidd specifies ashdl command that is invoked if this line matches. Do not use any shell filename expansion 
characters such as *, ?, or | (even quoted, they're not likey to work as intended). If the command succeeds, as indicated by 
its exit status, it is expected to have printed a single integer to standard output. This gives the value of this control line, to be 
used below. If the command fails, the line is ignored. The command is executed with its current directory set to the 
newsspool directory, /news/spool. 


The fourth field specifies the operator to use to test the value returned above It should be one of the two-letter numeric test 
operators defined in test(1) such as eq, it, and the like. The leading dash (-) should not be included. 





The fifth field specifies a constant with which to compare the value using the operator just defined. T his is done by invoking 
the command 


test value -operator constant 
Thelineis sad to “succeed” if it returns true. 


Theaxth field specifies what should be done if the line succeeds and in some cases if it fails. Any of the following words may 
be used: 


throttle Causes innwatch to throttle the server if this line succeeds. It also sets the state to the value of 
the line's label. If the line fails and the state was previously equal to the label on this line (that 
is, this line had previously succeeded), then a go command will be sent to the server, and 
innwatch will return to the run state The throttle is only performed if the current state is run 
or astate other than the label of thisline regardless of whether the command succeeds. 


pause Isidentical to throttle except that the server is paused. 

shutdown Sends a shutdown command to the server. It is for energency use only. 

flush Sends a flush command to the server. 

go Causes innwatch to send ago command to the server and to set the state to run. 
exit Causes innwatch to exit. 

skip The result of the control file is skipped for the current pass. 


Thelast fidd specifies the reason that is used in those ctlinnd commands that require one M ore strictly, it is part of the 
reason; innwatch appends some information to it. In order to enable other sites to recognize the state of the local inna server, 
this field should usually be set to one of several standard values. U Se No space if the server is rejecting articles because of a 
lack of filesystem resources. U se loadav if the server is rejecting articles because of alack of CPU resources. 


Once innwatch has taken some action as a consequence of its control line, it skips the rest of the control file for this pass. If 
the action was to restart the server (that is, issue a go command), then the next pass will commence almost immediately so 
that innwatch can discover any other condition that may mean that the server should be suspended again. 


EXAMPLES 


@@@df .;awk 'NR==2 {print $4}'@1t@10000@throttle@No space 
@@@df -i .;awk 'NR==2 {print $4}'@1t@1000@throttle@No space (inodes) 


The first line causes the server to be throttled if the free space drops bdow 10000 units (using whatever units df uses) and 
restarted again when free space increases above the threshold. 


The second line does the same for inodes. 


The next three lines act as a group and should appear in the following order. It is easier to explain then, howeve,, if they are 
described from the last up. 
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!load!load hiload! loadavg!1t!5!go! 
thiload:+ load: loadavg:gt:8: throttle: loadav 
/load/+/loadavg/ge/6/pause/loadav 


The final line causes the server to be paused if innwatch isin the run state and the load average rises to, or above six. The 
state is set to load when this happens. T he previous line causes the server to be throttled when innwatch isin the run or load 
state, and the load average rises above eight. T he state is set to hiload when this happens. N ote that innwatch can switch the 
server from paused to throttled if theload average rises from below six to between six and seven and then to aboveeight. T he 
first line causes the server to be sent a go command if innwatch isin the load Or hiload state and the load average drops below 
five. 


N ote that all three lines assume a mythical command loadavg that is assumed to print the current load average as an integer. 
In more practical circumstances, a pipe of uptime into awk ismore likely to be useful. 
BUGS 


This file must be tailored for each individual site; the sample supplied is truly no more than a sample. T he file should be 
ordered so that the more common problems are tested first. 


The run state is not actually identified by the labd with that three letter name, and using it will not work as expected. 
Using an “unusual” character for the ddimiter such as (, *, &, "", and the likeis likely to lead to obscure and hard-to-locate 
bugs. 


HISTORY 


Written by (kre@munnari.oz.au) for InterN &N ews. 


SEE ALSO 


innd(8), ctlinnd(8), news. daily(8) 


ipc 
ipc— System V interprocess communication mechanisms. 


SYNOPSIS 


include <sys/types.h> 
include <sys/ipc.h> 
include <sys/msg.h> 
include <sys/sem.h> 
include <sys/shm.h> 


DESCRIPTION 


The manual page refers to the Linux implementation of the Systen V interprocess communication mechanisms: message 
queues, semaphore sets, and shared memory segments. In the following, the word resource means an instantiation of one 
among such mechanisms. 


RESOURCE ACCESS PERMISSIONS 


For each resource, the system uses a common structure of type struct ipc_perm to storeinformation needed in determining 
permissions to perform an ipc operation. The ipc_perm structure, defined by the<sys/ipc.h> system header file, includes the 
following members: 


i i i 


ushort cuid; /* creator user id */ 
ushort cgid; /* creator group id */ 
ushort uid; /* owner user id */ 
ushort gid; /* owner group id */ 
ushort mode; /* r/w permissions */ 


The mode member of the ipc_perm structure defines, with its lower nine bits, the access permissions to the resource for a 
process executing an ipe systen call. The permissions are interpreted as follows: 


0400 Read by user. 
0200 W rite by user. 
0040 Read by group. 
0020 W rite by group. 
0004 Read by others. 
0002 W rite by others. 


Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. Furthermore “write” effectivdy means “alter” for a 
semaphore set. 


Thesame system header file defines also the following symbolic constants: 


IPC_CREAT Create entry if key doesn’t exists. 
IPC_EXCL Fail if key exists. 

IPC_NOWAIT Error if request must wait. 
IPC_PRIVATE Private key. 

IPC_RMID Remove resource. 

IPC_SET Se resource options. 

IPC_STAT Get resource options. 


N ote that 1Pc_PRIVATE iSakey_t type, whereas all the others symbolic constants are flag fields O Rable into an int type 
variable. 


MESSAGE QUEUES 


A message queue is uniquely identified by a positive integer (itsmsqia) and has an associated data structure of type struct 
msquid_ds, defined in <sys/msg.h>, containing the following members: 


struct ipc_perm msg_perm; 

ushort msg_qnum; /* no of messages on queue */ 
ushort msg_qbytes; /* bytes max on a queue */ 
ushort msg_lspid; /* pid of last msgsnd call */ 
ushort msg_Irpid; /* pid of last msgrcv call */ 
time_t msg _stime; /* last msgsnd time */ 

time_t msg _rtime; /* last msgrcv time */ 

time_t msg ctime; /* last change time */ 


msg_perm ipc_perm structure that specifies the access permissions on the message queue. 

msg_qnum N umber of messages currently on the message queue. 

msg_qbytes M aximum number of bytes of message text allowed on the message queue. 

msg_lspid ID of the process that performed the last msgsnd system call. 

msg_Irpid ID of the process that performed the last msgrev system call. 

msg_stime Time of the last msgsnd system call. 

msg_rtime Time of the last msgev system call. 

msg_ctime Time of the last system call that changed amember of themsqid_ds structure. 
SEMAPHORE SETS 


A semaphore set is uniquely identified by a positive integer (its semid) and has an associated data structure of type struct 
semid_ds, defined in <sys/sem.h>, containing the following members: 


struct ipc_perm sem_perm; 
time_t sem_otime; /* last operation time */ 
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time_t sem_ctime; /* last change time */ 
ushort sem_nsems; /* count of sems in set */ 


sem_perm ipce_perm structure that specifies the access permissions on the semaphore set. 

sem_otime Time of last semop system call. 

sem_ctime Time of last semct1 system call that changed a manber of the above structure or of one 
semaphore belonging to the set. 

sem_nsems N umber of semaphores in the set. Each sanaphore of the set is referenced by anon-negative 


integer ranging from @ to sem_nsems-1. 


A semaphore is a data structure of type struct sem containing the following members: 


ushort semval; /* semaphore value */ 

short sempid; /* pid for last operation */ 

ushort semncnt; /* no. of awaiting semval to increase */ 
ushort semzcnt; /* no. of awaiting semval = Q */ 


semval Senaphore value: a non-negative integer. 
sempid ID of the last process that performed a semaphore operation on this semaphore. 
semnent N umber of processes suspended awaiting for semvai to increase. 
semznt N umber of processes suspended awaiting for semval to become zero. 
SHARED MEMORY SEGMENTS 


A shared memory segment is uniquely identified by a positive integer (its shmid) and has an associated data structure of type 
struct shmid_ds, defined in <sys/shm.h>, containing the following members: 


struct ipc_perm shm_perm; 

int shm_segsz; /* size of segment */ 

ushort shm_cpid; /* pid of creator */ 

ushort shm_lpid; /* pid, last operation */ 
short shm_nattch; /* no. of current attaches */ 
time_t shm_atime; /* time of last attach */ 
time_t shm_dtime; /* time of last detach */ 
time_t shm_ctime; /* time of last change */ 


shm_perm ipc_perm structure that specifies the access permissions on the shared memory segment. 
shm_segsz Size in bytes of the shared memory segment. 
shm_cpid ID of the process that created the shared memory segment. 
shm_lpid ID of the last process that executed a shmat Or shmdt system call. 
shm_nattch N umber of current alive attaches for this snared memory segment. 
shm_atime Time of the last shmat system call. 
shm_dtime Time of the last shmat system call. 
shm_ctime Time of the last shmct1 system call that changed shmid_ds. 
SEE ALSO 


ftok(3), msgct1(2), msgget(2), msgrcv(2), msgsnd(2), semct1(2), semget(2), semop(2), shmat(2), shmct1(2), shmget(2), shmdt (2) 
Linux 0.99.13, 1 November 1993 


issue 


issue— | ssue identification file. 


lilo.conf 
DESCRIPTION 


The file /etc/issue isa text file that contains a message or system identification to be printed before the login prompt. It 
may contain various @char and \char sequences if supported by getty(1). 

FILES 
/etc/issue 


SEE ALSO 


getty(1), mota(5) 
Linux, 24 July 1993 


lilo.conf 


lilo.conf— Configuration file for LILO. 


DESCRIPTION 
This file, by default /etc/1ilo.conf, isread by the boot loader installer LILO (see 1i10(8)). 
It might look as follows: 


boot = /dev/hda 
delay = 40 
compact 

vga = normal 
root = /dev/hdat 


read-only 

image = /zImage-1.5.99 
abel = try 

image = /zImage-1.0.9 
abel = 1.0.9 

image = /tamu/vmlinuz 
abel = tamu 
root = /dev/hdb2 
vga = ask 

other = /dev/hda3 
abel = dos 








table = /dev/hda 


This configuration file specifies that LILO uses the M aster Boot Record on /dev/hda. (For a discussion of the various ways to 
use LILO and the interaction with other operating systems, see user. tex from the LILO documentation.) 


W hen booting, the boot loader will wait 4 seconds (40 deciseconds) for you to press Shift. If you don’t, then the first kernd 
image mentioned (/zImage-1.5.99, which you probably installed just 5 minutes ago) will be booted. If you do, the boot 
loader will ask you which image to boot. In case you forgot the possible choices, press T ab (or ?if you havea U.S. keyboard), 
and you will be presented with a menu. You now havethe choice of booting this brand new kernd, an old trusted kernd, or 
a kernel on anothe root file system (just in case you did something stupid on your usual root) or booting a different 
operating systen. There can be up to 16 images mentioned in 1ilo.conf. 


Ascan be seen previously, a configuration file starts with anumber of global options (the top six lines in the example), 
followed by descriptions of the options for the various images. An option in an image description will override a global 
option. 
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GLOBAL OPTIONS 


There are many possible keywords. T he description that follows is almost literally from user. tex (just Sightly abbreviated): 


backup=backup-file 


boot=boot-device 


compact 


default=name 


delay=tsecs 


disk=device-name 


disktab=disktab-file 


fix-table 


force-backup=backup-file 
ignore-table 


install=boot-sector 


linear 


lock 


map=map- file 


message=message-file 


nowarn 


Copy theoriginal boot sector to backup- file (which may also bea device, such as /dev/nu11) 
instead of /boot/boot.NNNN. 

Sets the name of the device (such as a hard disk partition) that contains the boot sector. If 
this keyword is omitted, the boot sector is read from (and possibly written to) the device 
that is currently mounted as root. 

Tries to merge read requests for adjacent sectors into asingle read request. T his drastically 
reduces load time and keeps the map smaller. U sing compact is especially recommended 
whe booting from a floppy disk. 

Uses the specified image as the default boot image. If default is omitted, the image 
appearing first in the configuration file is used. 

Specifies the number of tenths of a second the boot loader should wait before booting the 
first image. T hisis useful on systems that immediate y boot from the hard disk after 
enabling the keyboard. T he boot loader doesn’t wait if delay is omitted or is set to zero. 

D efines non-standard parameters for the specified disk. See section “Disk Geometry” of 
user. tex for details. 

Specifies the name of the disk parameter table. T he map installer looks for /etc/disktab if 
disktab is omitted. T he use of disktabs is discouraged. 

This allows LILO to adjust 3-D addressesin partition tables. Each partition entry contains a 
3-D (sector/head/cylinder) and alinear address of the first and the last sector of the 
partition. If a partition is not track-aligned and if certain other operating systems (such as 
PC/M S-DOS or OS/2) are using the same disk, they may change the 3-D address. LILO 
can store its boot sector only on partitions where both address types correspond. LILO 
readjusts incorrect 3-D start addresses if fix-table is set. 

W arning: T his does not guarantee that other operating systems may not attempt to reset the 
address later. It is also possible that this change has other, unexpected side effects. The 
correct fix isto repartition the drive with a program that does align partitions to tracks. 
Also, with some disks (such as some large EID E disks with address translation enabled), 
under some circumstances, it may even be unavoidable to have conflicting partition table 
entries. 

Like backup but overwrite an old backup copy if it exists. 

TeallsLILO to ignore corrupt partition tables. 

Install the specified file as the new boot sector. If install isomitted, /boot/boot.b is used as 
the default. 

Generate linear sector addresses instead of sector/head/cylinder addresses. Linear addresses 
are translated at runtime and do not depend on disk geometry. N ote that boot disks may 
not be portable if 1inear is used because the BIO S service to determine the disk geometry 
does not work rdiably for floppy disks. When using linear with large disks, /sbin/1lilo may 
generate references to inaccessible disk areas because 3-D sector addresses are not known 
before boot time 

Enables automatic recording of boot command lines as the defaults for the following boots. 
This way, LILO “locks” on a choice until it is manually overridden. 

Specifies the location of the map file If map is omitted, the file /boot /map is used. 

Specifies a file containing a message that is displayed before the boot prompt. N o message is 
displayed while waiting for a shifting key after printing L1Lo . In the message, the Fr 
character (C tri+L) clears the local screen. The size of the message file is limited to 65,535 
bytes. The map file has to be rebuilt if the message file is changed or moved. 

Disables warnings about possible future dangers. 


lilo.conf 


optional The per-image option optional applies to all images. 

password=pass word The per-image option password=... applies to all images. 

prompt Forces entering the boot prompt without expecting any prior key presses. U nattended 
reboots are impossible if prompt is set and timeout isn’t. 

restricted The per-image option restricted applies to all images. 

serial=parameters Enables control from a serial line The specified serial port is initialized and the boot loader 


is accepting input from it and from the PC's keyboard. Sending a break on the sevial line 
corresponds to pressing a Shift key on the console in order to get the boot loade’’s 
attention. All boot images should be password-protected if the serial access is less secure 
than access to the console, such asif the line is connected to a modem. The parameter string 
has the following syntax: 
<port>[,<bps>[<parity>[<bits>]]] 
<port >: Thenumber of the serial port, zero-based. @ corresponds to COM 1 alias /dev/ttyso, 
and so on. All four ports can be used (if present). <bps >: T he baud rate of theserial port. 
The following baud rates are supported: 110, 150, 300, 600, 1200, 2400, 4800, and 9600 
bps. D efault is 2400 bps. 
<parity>: T he parity used on the sevial line The boot loader ignores input parity and strips 
the eighth bit. T he following (uppercase or lowercase) characters are used to describe the 
parity: n for no parity, e for even parity, and o for odd parity. 
<bits>: Thenumber of bitsin a character. O nly 7 and 8 bits are supported. D efault is 8 if 
parity is none and 7 if parity is even or odd. 
If serial iSset, the value of delay is automatically raised to 20. For example serial=0,2400n8 
initializes CO M 1 with the default parameters. 

timeout=tsecs Sets a time-out (in tenths of a second) for keyboard input. If no key is pressed for the 
specified time, the first image is automatically booted. Similarly, password input is aborted 
if the user isidle for too long. The default time out is infinite. 

verbose=l evel Turnson alot of progress reporting. Higher numbers give more verbose output. If -v is 
additionally specified on the LILO command line, the level is increased accordingly. The 
maximum verbosity level iss. 


Additionally, the kernel configuration parameters append, ramdisk, read-only, read-write, root, and vga Can be set in the 
global options section. T hey are used as defaults if they aren’t specified in the configuration sections of the respective kernel 
images. 
PER-IMAGE SECTION 
A per-image section starts with athe a line 
image=pat hname 
to indicate a file or device containing the boot image of a Linux kernel or a line 
other=pat hname 
to indicate an arbitrary system to boot. 


In the former case, if an image line specifies booting from a device then one has to indicate the range of sectors to be mapped 
using 
range=st art -end 


In the latter case (booting another system), there are the three options: 


loader=chain-|oader This specifies the chain loader that should be used. By default, /boot/chain.b is used. The 
chain loader must be specified if booting from a device othe than the first hard or floppy 
disk. 
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table=device This specifies the device that contains the partition table The boot loader will not pass 
partition information to the booted operating system if this variable is omitted. (Some 
operating systems have other means to determine from which partition they have ben 
booted. For example MS-DOS usually stores the geometry of the boot disk or partition in 
its boot sector.) N ote that /sbin/1ilo must be rerun if apartition table mapped referenced 
with table is modified. 

unsafe Do not access the boot sector at map creation time T his disables some sanity checks, 
including a partition table check. If the boot sector is on afixed-format floppy disk device, 
using uNsaFE avoids the need to put a readable disk into the drive when running the map 
installer. unsafe and table are mutually incompatible 


In both cases, the following options apply: 


label=name The boot loader uses the main filename (without its path) of each image specification to 
identify that image. A different name can be used by setting the variable 1abe1. 

alias=name A second name for the same entry can be used by specifying an alias. 

lock (See previous description.) 

optional Omit the image if it is not available at map creation time. T his is useful to specify test 
kernds that are not always present. 

password=pass word Protect the image by a password. 

restricted A password is only required to boot the image if parameters are specified on the command 
line (such as single). 

KERNEL OPTIONS 
If the booted image is a Linux kernd, then one may pass command-line parameters to this kernel. 
append=string Appends the options specified to the parameter line passed to the kernal. T his is typically 


used to specify parameters of hardware that can’t be entirely autodetected or for which 
probing may be dangerous. Example append = "hd=64,32,202". 

literal=string Like append but removes all other options (such as setting of the root device). Because vital 
options can be removed unintentionally with 1itera1, this option cannot be set in the 
global options section. 


ramdisk=si ze This specifies the size of the optional RAM disk. A value of zero indicates that no RAM disk 
should be created. If this variable is omitted, the RAM disk size configured into the boot 
image is used. 

read-only This specifies that the root filesystem should be mounted read-only. Typically, the system 
startup procedure renounts the root filesystem read-write later (such as after tscking it). 

read-write This specifies that the root filesystem should be mounted read-write. 

root=root-device This specifies the device that should be mounted as root. If the special name current is used, 


the root device is set to the device on which the root filesystem is currently mounted. If the 
root has been changed with -r, the respective device is used. I f the variable root is omitted, 
the root device setting contained in the kernd image is used. (T hat is set at compile time 
using the root bev variable in the kernel makefile and can later be changed with the rdev(8) 
program.) 

vga=mo de This specifies the VGA text mode that should be selected when booting. The following 
values are recognized (case is ignored): 
normal: Select normal 80x25 text mode. 
extended (or ext): Sdect 80x50 text mode. 
ask: Stop and ask for user input (at boot time). 
<number >: Use the corresponding text mode. A list of available modes can be obtained by 
booting with vga=ask and pressing Enter. 


moderators [as] 


If this variable is omitted, the VGA modesetting contained in the kernd imageis used. 
(That is set at compile time using the svca move variable in the kernel makefile and can later 
be changed with the rdev(8) program.) 


SEE ALSO 
1ilo(8), rdev(8). The LILO distribution comes with very extensive documentation of which the preceding information is an 
extract. 


28 July 1995 


MAKEDEV .cfg 


MAKEDEV.cfg— Configuration for makEDEv(8). 


DESCRIPTION 


MAKEDEV. cfg is a text file that tells makeDev(8) what to do (and equally importantly, what not to do). U nlike pevinro(5), which 
ismeant to be centrally maintained, it contains all local configuration for a particular site and all customization. T here are 
basically two kinds of declaration in this file a “class” declaration and an “omit” declaration. 


A class declaration has the form 


class name : owner group- owner permissions 


This says that any devices placed in the specified class by pevinro should be created with this ownership and these permis- 
sions. A sample entry might be 

class public: root system 0666 

This says that devices marked public should be owned by root.system and have mode ées. 

An omit declaration has the form 


omit { device... } 


This causes the specified devices to never be created, even if explicitly specified. U se caution when setting this up. The intent 
isto be able to run maKEDev update and not haveit create all sorts of useless devices you’d never use. 


SEE ALSO 
MAKEDEV(8), DEVINFO(5) 
Versgon 1.4, January 1995 


moderators 


moderators— M ail addresses for moderated U senet newsgroups. 


DESCRIPTION 
T he GetModeratorAddress(3) routine reads thefile /news/1ib/moderators to determine how to reach the moderator of a 
newsgroup. This is used by inews(1) when an unapproved local posting is made to a moderated newsgroup. 
Thefile is read until a match is found. Blank lines and lines starting with a number sign (#) are ignored. All other lines 
should consist of two fidds separated by acolon. 
The first field is a wildmat(3)-style pattern. If it matches the name of the newsgroup, then the second fidd istaken to bea 
format string for sprintt(3). T his string should have at most ones paramete,, which will be given the name of the 
newsgroup with periods transliterated to dashes. 


fas | Part V: FileFormats 


Hereisasample file 


foo. important: announce -request@foo.com 
foo.*:%s@mailer.foo.com 
gnu.*:%s@prep.ai.mit.edu 
:%s@uunet.uu.net 


Using this file, postings to the moderated newsgroup in theleft column will be sent to the address shown in the right 
column: 


foo.important announce-request@foo.com 
foo.x.announce foo-x-announce@mailer.foo.com 
gnu.emacs.sources gnu-emacs-sources@prep.ai.mit.edu 
comp.sources.unix comp-sources-unix@uunet.uu.net 


HISTORY 


Written by Rich $alz (rsalze@uunet.uu.net) for InterN etN ews. 


SEE ALSO 
inews(1), inn.conf(5), libinn(3), wildmat(3) 


/etc/modules 


/etc/modules— Kernel modules to load at boot time. 


DESCRIPTION 


The /etc/modules file contains the names of kernel modules that are to be loaded at boot time, onepe line Comments 
begin with a #, and everything on the line after then are ignored. 


Debian GNU /Linux version 0.93 


motd 


motd— M essage of the day. 


DESCRIPTION 
The contents of /etc/motd are displayed by 1ogin(1) after asuccessful login but just before it executes the login shell. 


The mota stands for “message of the day,” and this file has been traditionally been used for exactly that. (It requires much less 
disk space than mail to all users.) 


FILES 
/etc/motd 


SEE ALSO 
login(1) issue(5) 
Linux, 29 D cenber 1992 


mtools 


mtools— T ableof DOS devices. 


mtools [| 
DESCRIPTION 


/etc/mtools.conf and ~/.mtoolsre are the configuration files for mtools. T hese configuration files describe the following 
items: 

Global configuration flags and variables 

Pe-drive flags and variables 

Character translation tables 


/etc/mtools.conf is the system-wide configuration file, and ~/.mtoo1src is the user's private configuration file. 


GENERAL SYNTAX 


The configuration files is made up of sections. Each section starts with a keyword identifying the section followed by a colon. 
Then follow variable assignments and flags. Variable assignments take the following form: 


name=value 


Flags are lone keywords without an equal sign and va! ue following them. A section eather ends at the end of the file or where 
the next section begins. 


Lines starting with a hash (#) are comments. N ewline characters are equivalent to whitespace (exceot where ending a 
comment). The configuration file is case insensitive, except for items enclosed in quotes (such as filenames). 


DEFAULT VALUES 


For most platforms, mtools contains reasonable compiled-in defaults. You usually don’t need to bother with the configura- 
tion file if all you want to do with mtools isaccess your floppy drives. On the other hand, the configuration file is needed if 
you also want to use mtools to access your hard disk partitions and dosemu image files. 


GLOBAL VARIABLES 
Global variables may be set to 1 or to a. 
The following global flags are recognized: 





MTOOLS_SKIP_CHECK If this is set to 1, mtools skips most of its sanity checks. Thisis needed to read some Atari 
disks that have been made with the earlier ROMs and that would not be recognized 
otherwise 

MTOOLS_FAT_COMPATIBILITY If this is set to 1, mtools skipsthe FAT size checks. Some disks have a bigger FAT than they 
really need. T hese are rejected if this option is not set. 

MTOOLS_LOWER_CASE If this is set to 1, mtools displays all-uppercase short filenames as lowercase. T his has been 
doneto allow a behavior that is consistent with older versions of mtools, which didn’t know 
about the case bits. 

For example, inserting the following line into your configuration file instructs mtoo1s to skip the sanity checks: 


MTOOLS_SKIP_CHECK=1. 
Global variables may also be set via the environment: export MTOOLS_SKIP_CHECK=1. 


PER-DRIVE FLAGS AND VARIABLES 
Per-drive flags and values may be described in a drive section. A drive section starts with drive driveletter:. 
Then follow variable-value pairs and flags. 

GENERAL PURPOSE DRIVE VARIABLES 
The following variables are available: 


file The name of the file or device holding the disk image. Thisis mandatory. The filename 
should be enclosed in quotes. 
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use_xdf If this is set to anonzero value, mtools also tries to access this disk as an Xdf disk. Xdfisa 
high-capacity format used by O S/2. This is off by default. 
partition Tells mtoo1s to treat the driveas a partitioned device and to use the given partition. Only 


primary partitions are accessible using this method, and they are numbered from 1 to 4. For 
logical partitions, use the more general offset variable. The partition variable is intended 
for Syquests, ZIP drives, and DO SEM U hdimages. It is not recommended for hard disks to 
which direct access to partitions is available. 

offset Describes wherein the file the M S-D OS filesystem starts. T his is useful for logical partitions 
in DOSEM U hdimages and for AT ARI RAM disks. By default, thisis zero, meaning that 
the filesystem starts right at the beginning of the device or file 

fat_bits Thenumber of FAT bits. Thiscan be 12 or 16. T hisis very rarely needed because it can 
almost always be deduced from information in the boot sector. On the contrary, describing 
the number of fat bits can actually be harmful if you get it wrong. You should only useit if 
mtools gets the autodetected number of fat bits wrong or if you want to mformat a disk with 
a weird number of fat bits. 


Only the file option is mandatory. The other parameters may be left out. In that case, a default value or an autodetected 
value is used. 


DRIVE GEOMETRY CONFIGURATION 
Geoméatry information describes the physical characteristics about the disk. Its has three purposes: 


mformat The geometry information is written into the boot sector of the newly made disk. H oweve, 
you may also describe the geometry information on thecommand line. See mformat(1) for 
details. 

filtering On some Unices, device nodes only support one physical geometry. The geometry is 


compared to the actual geometry stored on the boot sector to make sure that this device 
node is able to correctly read the disk. If the geometry doesn’t match, this drive entry fails, 
and the next drive entry bearing the same drive letter is tried. See the next section “Supply- 
ing M ultiple D escriptions for aD rive” for more details on supplying several descriptions for 
a drive letter. 
If no geometry information is supplied in the configuration file, all disks are accepted. On 
Linux (and on Sparc), there exist device nodes with configurable geometry (/dev/fde, /dev/ 
fd1 etc), $0 filtering is not needed (and ignored) for disk drives. (mtoo1s still does do 
filtering on plain files (disk images) in Linux: This is mainly intended for test purposes 
because! don’t have access to aU NIX that would actually need filtering.) 

initial geometry The geometry information (if available) is also used to set the initial geometry on 
configurable device nodes. This initial geometry is used to read the boot sector, which 
contains the real geometry. If no geometry information is supplied in the configuration file, 
no initial configuration isdone On Linux, thisis not really needed either because the 
configurable devices are able to autodetect the disk type accurately enough (for most 
common formats) to read the boot sector. 


W rong geometry information may lead to very bizarre errors. That's why | strongly recommend that you don’t use geometry 
configuration unless you really need it. 

The following geometry related variables are available: 

cylinders Thenumber of cylinders. 

heads Thenumber of heads (sides). 

sectors The number of sectors per track. 
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For example, the following drive section describesa1.44M drive: 


drive a: 
file="/dev/fd0H1440" 
fat_bits=12 

tracks=80 heads=2 sectors=18 


The following shorthand geometry descriptions are available 


1.44M High density, 3 1/2 disk. Equivalent to fat_bits=12 tracks=80 heads=2 sectors=18. 
1.2M High density, 5 1/4 disk. Equivalent to fat_bits=12 tracks=80 heads=2 sectors=15. 
720K Double density, 3 1/2 disk. Equivalent to fat_bits=12 tracks=80 heads=2 sectors=9. 
360K D ouble density, 5 1/4 disk. Equivalent to fat_bits=12 tracks=40 heads=2 sectors=9. 


The shorthand format descriptions may be amended. For example, 360k sectors=8 describes a 320K disk and is equivalent to 
fat_bits=12 tracks=40 heads=2 sectors=8. 


OPEN FLAGS 
M oreover, the following flags are available: 


sync All 1/O operations are done synchronously. 

nodelay The device or file is opened with the o_npeELay flag. This is needed on some non-Linux 
architectures. 

exclusive Thedeviceor file is opened with the o_exct flag. On Linux, this ensures exclusive access to 


the floppy drive. On most other architectures and for plain files, it has no effect at all. 


SUPPLYING MULTIPLE DESCRIPTIONS FOR A DRIVE 


It is possible to supply multiple descriptions for a drive In that case the descriptions are tried in order until oneis found 
that fits. D escriptions may fail for several reasons: 


m Thegeometry is not appropriate 
m Thereisno disk in thedrive 
m Othe problems 


M ultiple definitions are useful when using physical devices that are only able to support one single disk geometry: 


drive a: file="/dev/fd0H1440" 1.44m 
drive a: file="/dev/fd0H720" 720k 


This instructs mtools to use /dev/fd0H1440 for 1.44M (high density) disks and /dev/fdoH720 for 720K (double density) disks. 
On Linux, this feature is not really needed because the /dev/fdo device is able to handle any geometry. 
You can also use multiple drive descriptions to access both of your physical drives through one drive letter: 


drive z: file="/dev/fdo" 
drive z: file="/dev/fd1" 


With this description, mdir z: accesses your first physical drive if it containsa disk. If the first drive doesn’t contain a disk, 
mtools checks the second drive. 


W hen using multiple configuration files, drive descriptions in the files parsed last override descriptions for the same drive in 
earlier files. In order to avoid this, usethedrive+ or +drive keywords instead of drive. The first adds a description to the end 
of the list (will be tried last), and the second adds it to the start of the list. 

CHARACTER TRANSLATION TABLES 


If you livein the U SA, in Western Europe or in Australia, you can skip this section. 
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INTRODUCTION 


DOS uses a different character code mapping from UNIX. Seven-bit characters still have the same meaning; only characters 
with the eight-bit set are affected. To make matters worse, there are several translation tables available depending on the 
country where you are The appearance of the characters is defined using code pages. T hese code pages aren't the same for all 
countries. For instance, some code pages don’t contain upper -case accented characters. On the other hand, some code pages 
contain characters that don’t exist in UNIX, such as certain line. drawing characters or accented consonants used by some 
Eastern European countries. T his affects two things rdating to filenames: 


U ppercase characters In short names, only uppercase characters are allowed. This also holds for accented 
characters. For instance, in a code page that doesn’t contain accented uppercase characters, 
the accented lowercase characters get transformed into thar unaccented counterparts. 

Long filenames M icrosoft has finally cometo thar senses and uses a more standard mapping for the long 
filenames. They use U nicode, which is basically a 32-bit version of ASCII. Its first 256 
characters are identical to UNIX ASCII. Thus, the code page also affects the correspondence 
between the codes used in long names and those used in short names. 


mtools considers the filenames entered on thecommand line as having the UNIX mapping and translates the characters to 
get short names. By default, code page 850 is used with the Swiss uppercase/lowercase mapping. | chose this code page 
because its set of existing characters most closely matches UN1X’s. M oreover, this code page covers most characters in use in 
the USA, Australia, and W estern Europe. H owever, it isstill possible to chose a different mapping. T here are two methods: 
the country variable and explicit tables. 


CONFIGURATION USING COUNTRY 


The country variable is recommended for people that also have access to M S-D OS system files and documentation. If you 
don’t have access to these, I’d suggest you use explicit tables instead. 


Syntax: COUNTRY=" country [,[ codepage ], country.sys ]" 


This tells mtoo1s to use a UNIX-to-D OS translation table that matches codepage and an lowercase to-uppercase table for 
country and to usethecountry. sys fileto get the lowercase to-uppercase table. The country code is most often the telephone 
prefix of the country. Refer to the DOS help page on country for more details. Thecodepage and the country. sys parameters 
are optional. D on’t type in the square brackets; they are only there to indicate which parameters are optional. The 
country.sys fileis supplied with MS-DOS. In most cases, you don’t need it because the most common translation tables are 
compiled into mtoo1s. Don’t worry if you run aU N IX-only box that lacks this file 





If codepage isnot given, aper-country default code page is used. If the country. sys parameter isn’t given, compiled-in 
defaults are used for the lowercase-to-uppercase table. T his is useful for other U nices than Linux, which may have no 
country. sys file available online. 

TheUNIX-to-D OS arenot contained in the country. sys file and thus mtools always uses compiled-in defaults for those 
Thus, only alimited amount of code pages are supported. If your preferred code page is missing, or if you know the name of 
the W indows 95 file that contains this mapping, drop mea line at Alain. knaff@inrialpes.fr. 


The country variable can also be set using the environment. 


CONFIGURATION USING EXPLICIT TRANSLATION TABLES 
Translation tables may be described in lines in the configuration file. T wo tables are needed: first the D 0 S-to-UN IX table 
and then the lowercase-to- uppercase table A DO S-to-UN IX table starts with the tounix keyword, followed by acolon and 
128 hexadecimal numbers. A lower-to-upper table starts with the fucase keyword, followed by acolon and 128 hexadecimal 
numbers. 


The tables only show the translations for characters whose codes is greater than 128 because translation for lower codesis 
trivial. Example: 


mtools 1157 


tounix: 


Oxc7 Oxfc Oxe9 Oxe2 Oxe4 OxeO Oxed Oxe7 
Oxea Oxeb Oxe8 Oxef Oxee Oxec Oxc4 Oxcd 
O@xc9 Oxe6 Oxc6 Oxf4 Oxté Oxf2 Oxfb Oxf9 
Oxff Oxd6 Oxdc Oxf8 Oxa3 Oxd8 Oxd7 Oxd5f 
Oxe1 Oxed Oxf3 Oxfa Oxf1 Oxd1 Oxaa Oxba 
Oxbf Oxae Oxac Oxbd @xbc Oxal Oxab Oxbb 
Ox5f Ox5f Ox5f Ox5f Ox5f Oxct Oxc2 Oxcd 
OxaQ9 OxSf Ox5f Ox5F Ox5Ff Oxa2 Oxad Oxac 
Ox5f Ox5f Ox5f Ox5f Ox5f Ox5f Oxe3 Oxc3 
OxSf OxSf OxSF OxSF OxSf OxS5F Ox5F Oxa4 
Oxf® Oxd® Oxc9 Oxch Oxc8 Ox69 Oxcd Oxce 
Oxcft OxSf Ox5f Ox5F Ox5Ff Ox7c Ox49 OxdF 
Oxd3 Oxdf Oxd4 Oxd2 Oxf5 Oxd5 Oxb5 Oxfe 
Oxde Oxda Oxd9 Oxfd Oxdd Oxde Oxaf Oxb4 
Oxad Oxb1 Ox5f Oxbe O@xb6 Oxa7 Oxf7 Oxb8 
OxbO Oxa8 Oxb7 Oxb9 Oxb3 Oxb2 Oxd5f Ox5F 


fucase: 


Ox80 Ox9a Ox90 Oxb6 Ox8e Oxb7 Ox8f Ox8d 
Oxd2 Oxd3 Oxd4 Oxd8 Oxd7 Oxde Ox8e Ox8f 
Ox90 Ox92 Ox92 Oxe2 Ox99 Oxe3 Oxea Oxeb 
Ox59 Ox99 Ox9a Ox9d Ox9c Ox9d Ox9e Ox9F 
Oxb5 Oxd6 Oxe® Oxe9 Oxad Oxad Oxab Oxa7 
Oxa8 Oxa9 Oxaa Oxab Oxac Oxad Oxae Oxaf 
OxbO Oxb1 Oxb2 Oxb3 @xb4 Oxb5 Oxb6 Oxb7 
Oxb8 Oxb9 Oxba Oxbb @xbc Oxbd Oxbe Oxbf 
Oxc® Oxc1 Oxc2 Oxc3 Oxc4 Oxc5 Oxc7 Oxc7 
Oxc8 Oxc9 Oxca Oxcb Oxcc Oxcd Oxce Oxcf 
Oxd1 Oxd1 @xd2 Oxd3 @xd4 0x49 Oxd6 Oxd7 
O@xd8 Oxd9 Oxda Oxdb O@xdc Oxdd Oxde Oxdf 
Oxe® Oxe1 Oxe2 Oxe3 Oxed5 Oxed Oxe6 Oxe8 
Oxe8 Oxe9 Oxea Oxeb Oxed Oxed Oxee Oxef 
Oxf Oxt1 Oxf2 Oxf3 Oxt4 Oxfd5 Oxf6 Oxf7 
Oxf8 Oxf9 Oxfa Oxfb Oxfc Oxfd Oxfe Oxff 


The first table maps DOS character codes to UNIX character codes. For example the DOS character number 129 isau with 
two dots on top of it. To translate it into UN 1X, welook at the character number 1 in thefirst table (1 =129 - 128). Thisis 
oxfc. (Beware; numbering starts at 0.) The second table maps lowercase D OS characters to uppercase D OS characters. The 
same lowercase u with dots maps to character ox9a, which is an uppercase U with dots in DOS. 


UNICODE CHARACTERS GREATER THAN 256 


If an existing M S-D OS name contains U nicode character greater than 256, these are translated to underscores or to 
characters that are closein visual appearance. For example, accented consonants are translated into their unaccented 
counterparts. T his translation is used for mdir and for the UNIX filerames generated by mcopy. Linux does support U nicode 
too, but unfortunately, too few applications support it yet to bother with it in mtools. M ost importantly, xterm can’t display 
Unicode yet. If there is sufficient demand, | might include support for U nicodein the UN IX filenames as well. 

Caution: W hen deleting files with mtoo1s, the underscore matches all characters that can’t be represented in UNIX. Be 
careful before mde1! 


LOCATION OF CONFIGURATION FILES AND PARSING ORDER 
The configuration files are parsed in the following order: 
Compiled-in defaults 
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/etc/mtools. conf 

/etc/mtools. T his is for backwards compatibility only and is only parsed if mtools.conf doesn’t exist. 

~/.mtoolsre 

O ptions described in the later files override those described in the earlier files. D rives defined in earlier files persist if they are 
not overridden in the later files. For instance, drives A and B may be defined in /etc/mtools.conf and drivesC and D may be 
defined in ~/.mtoolsrc. H owever, if ~/.mtoolsrc also defines driveA, this new description would override the description of 
driveA in /etc/mtools.conf instead of adding to it. If you want to add a new description to adrive already described in an 
earlier file, you need to use either the +drive or drive+ keywords. 


BACKWARDS COMPATIBILITY 


The syntax described herein is new for version mtools 2.5.4. The old line-oriented syntax is still supported. Each line 
beginning with a single letter is considered to be a drive description using the old syntax. O Id style and new style drive 
sections may be mixed within the same configuration file to make upgrading easier. Support for the old syntax will be phased 
out eventually, and to discourage its use, | purposefully omit its description here. 


FILES 


/etc/mtools. conf 


“/.mtoolsre 


SEE ALSO 


mtools(1) 
5 December 1995 


newsfeeds 


newsfeeds— D eermine where U senet articles get sent. 


DESCRIPTION 


Thefile /news/1ib/newsfeeds specifies how incoming articles should be distributed to other sites. It is parsed by the 
InterN etN ews server inna(8) when it starts up or when directed to by ct1inna(8). 


The file is interpreted as a set of lines according to the following rules. If a line ends with a backslash, then the backslash, the 
newline and any whitespace at the start of the next line is deleted. T his is repeated until the entire “logical” line is collected. 
If the logical lineis blank or starts with anumber sign (4), it isignored. 


All other lines are interpreted as feed entries. An entry should consist of four colon-separated fidds; two of the fidds may 
have optional subfidds, marked off by a slash. Fields or subfidds that take multiple parameters should be separated by a 
comma. Extra whitespace can cause problems. Except for the site names, case is significant. The format of an entry is 


sitename[/exclude,exclude,...]\ 
rpattern,pattern...[/distrib,distrib...]\ 
tflag,flag...\ 

tparam 


Each fidd is described below. 


Thesitename isthenameof thesite to which anewsarticle can besent. It is used for writing log entries and for determining 
if an article should be forwarded to asite. If sitename already appears in the article's Path header, then the article will not be 
sent to the site. The name is usually whatever the remote site uses to identify itself in the Path line but can be almost any 
word that makes sense special local entries (such as archivers or gateways) should probably end with an exclamation point to 
make sure that they do not have the same name as any real site For example, gateway isan obvious name for the local entry 
that forwards articles out to a mailing list. |f asite with the name gateway posts an article when the local site receives the 


newsfeeds 


article, it will see the namein the Path and not send the article to its own gateway entry. If an entry has an exclusion subfidd, 
then the article will not be sent to that site if any of the names specified as excludes appear in the Path header. Thesame 
sitename can be used more than once; the appropriate action will be taken for each site that should recave the article, 
regardless of the name, although this is recommended only for program feeds to avoid confusion. C ase is not significant in 
site names. 


The patterns specify which groups to send to thesite and are interpreted to build a “subscription list” for the site The 
default subscription is to gé all groups. The patterns in the field are wildmat(3)-style patterns and are matched in order 
against the list of newsgroups that the local site receives. If the first character of a pattern is an exclamation mark, then any 
groups matching the pattern are renoved from the subscription; otherwise, any matching groups are added. For example, to 
receive all comp groups but only comp. sources. unix within the sources newsgroups, the following set of patterns can be used: 


comp.*, !comp.sources.*,comp.sources.unix 


Thee are three things to note about this example. The first isthat thetrailing .* isrequired. The second is that, again, the 
result of the last match is the most important. Thethird is that comp.sources.* Could be written as comp.sources*, but this 
would not have the same effect if there were a comp. sources- only group. 


See innd(8) for details on the propagation of control messages. 


A subscription can be further modified by specifying “distributions” that the site should or should not recave. The default is 
to send all articles to all sites that subscribe to any of the groups where it has been posted, but if an article has a D istribution 
header and any distribs are specified, then they are checked according to the following rules: 


1. If the Distribution header matches any of the values in the subfield, then the article is sent. 

2. If adistrib starts with an exclamation point and it matches the Distribution header, then the article is not sent. 

3. If Distribution header does not match any distrib in the site's entry and no negations were used, then the article isnot 
sent. 

4. \f Distribution header does not match any distrib in the site’s entry and any distrib started with an exclamation point, 
then thearticleis sent. 


If an article has more than one distribution specified, then each one is evaluated according to the preceding rules. If any of 
the specified distributions indicate that the article should be sent, it is. If none do, it isnot sent: The rules are used asa 
“logical or.” It isalmost definitely a mistake to havea single feed that specifies distributions that start with an exclamation 
point along with some that don't. 


Distributions are text words, not patterns; it is usually a mistake to have entries like * or a11 there 


Theflags parameter specifies miscellaneous parameters. T hey may be specified in any order; flags that take values should 
have the value immediately after the flag letter with no whitespace. T he valid flags are 


< size An article will only be sent to the site if it isless than size bytes long. T he default isno 
limit. 

A checks An article will only be sent to the site if it meets the requirements specified in thechecks, 
which should be chosen from the following set: 
d Distribution header required 
p Do not check Path header before propagating. 

B high/low If asite is being fed by afile, channd, or exploder, the server will usually start trying to write 


the information as soon as possible Providing a buffer may give better system performance 
and help smooth out overall load if a large batch of news comes in. T he value of the this flag 
should be two numbers separated by aslash. T hefirst specifies the point at which the server 
can start draining the feed’s!/O buffer, and the second specifies when to stop writing and 
begin buffering again; the units are bytes. T he default isto do no buffering, sending output 
as soon as it is possible to do so. 

F name This flag specifies the name of the file that should be used if it is necessary to begin spooling 
for the site. If nameisnot an absolute pathname, it is taken to be relative to /news/spool/ 
out.going. Then, if the destination isa directory, the file to go in that directory will be used 
as filename 
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G count 


H count 


I size 


N modifiers 


S size 


T type 


W items 


If this flag is specified, an article will only be sent to the site if it is posted to no morethan 
count Newsgroups. 
If this flag is specified, an article will only be sent to the site if it hascount or fewer sites in 
its Path line. This flag should only be used as arough guide because of the loose interpreta- 
tion of the Path header; some sites put the poster’s name in the header, and some sites that 
might logically be considered to be one hop become two because they put the posting 
workstation’s name in the header. The default value for count isone 

The flag specifies the size of the internal buffer for a file feed. If there are more file feeds 
than allowed by the system, they will be buffered internally in least recently used order. If 
the internal buffer grows bigger than size bytes, however, the data will be written out to the 
appropriate file 

The newsgroups that a site receives are modified according to the modifiers, which should 
be chosen from the following set: 

m Only moderated groups 

u Only unmoderated groups 

If the amount of data queued for the site gets to belarger than size bytes, then the server 
will switch to spooling, appending to a file specified by ther flag or /news/spool/out.going/ 
sitename if the F flag is not specified. Spooling usually happens only for channel or exploder 
feeds. 

This flag specifies the type of feed for the site type should bea letter chosen from the 
following set: 





c Channd 

f File 

1 Log try only 

m Funnel (multiple entries feed into one) 

p Program 

x Exploder. Each feed is described in the section on feed types. 


The default is tr. 

If asiteis fed by file channel, or exploder, this flag controls what information is written. If 
asiteisfed by a program, only the asterisk (*) has any effect. The items should be chosen 
from the following set: 


b Size of the article in bytes. 

f Article's full pathname 

g The newsgroup the article isin; if cross-posted, then the first of the groups 
this site gets. 

m Article's M essage-ID . 

n Article's pathname relative to the spool directory. 

p The site that fed the article to the server; from the Path header. 

s TheIP address of the site that sent the article 

t Time article was received as seconds since epoch. 

* N ames of the appropriate funnel entries; or all sites that get the article 

D Value of the Distribution header; ? if none present. 

H All headers. 

N Value of the N ewsgroups header. 

0 Overview data. 

R 


Information needed for replication. M ore than one letter can be used; the 
entries will be separated by a space and written in the order in which they are 
specified. The default is wn. 


newsfeeds 


Theu and 0 items are intended for use by programs that create news overview databases. If H 
is present, then the all the article's headers are written followed by a blank line. An Xref 
header (even if one does not appear in the filed article) and a Bytes header, specifying the 
article's size, will also be part of the headers. If used, this should be the only item in the list; 
if preceded by other items, however, anewline will be written before the headers. Theo 
generates input to the overchan(8) program. It, too, should be the only item in the list. 

T he asterisk has special meaning. It expands to a space separated list of all sites that received 
the current article If the site is the target of a funnel, however (that is, it is named by othe 
sites that have a Tm flag), then the asterisk expands to the names of the funnd feeds that 
received the article. If thesite is fed by a program, then an asterisk in the param field will be 
expanded into the list of funnd feeds that received the article A site fed by aprogram 
cannot get the site list unless it is the target of other Tm feeds. 


The interpretation of the param field depends on the type of feed, and is explained in more detail in the section on feed types. 
It can be omitted. 


Thesite named me is special. T here should only be one such entry, and it should be thefirst entry in the file. If theme entry 
has a subscription list, then that list is automatically prepended to the subscription list of all other entries. For example, 

*, !control, !junk, !foo.* can be used to set up theinitial subscription list for all feeds so that local postings are not propa- 
gated unless foo. * explicitly appears in the site’s subscription list. N ote that most subscriptions should have ! junk, !control 
in thar pattern list; see the discussion of control messages in innd(8). (Unlike other news software, it does not affect what 
groups are rece ved; that is done by the active(5) file) 


If the we entry has a distribution subfidd, then only articles that match the distribution list are accepted; all other articles are 
rejected. A commercial news server, for example, might have /!10ca1 to rgect local postings from other, misconfigured, sites. 


FEED TYPES 


innd provides four basic types of feeds: log, file, program, and channd. An exploder is a special type of channdl. In addition, 
several entries can feed into the same feed; these are funnd feeds, which refer to an entry that is one of the other types. N ote 
that the term “feed” is technically a misnomer because the server does not transfer articles but reports that an article should 
be sent to thesite. 


The simplest feed is one that is fed by alog entry. O ther than a mention in the news logfile, no data is ever written out. This 
is equivalent to at entry writing to /dev/nul1 except that no file is opened. 


A site fed by afile is simplest type of feed. When the site should receive an article one line is written to the filenamed by the 
param field. If paramiSnot an absolute pathname, it is taken to berdative to /news/spool/out.going. If anpty, the filename 
defaults to /news/spool/out.going/sitename. | hisnameshould be unique 


When asite fed by a file is flushed (see ct1innd), the following steps are performed. T hescript doing the flush should have 
first renamed the file. The server tries to write out any buffered data and then closes the file. The renamed fileis now 
available for use. The server will then reopen the original file, which will now get created. 


A site fed by aprogram has a process spawned for every article that the site receives. The param fidd must be a sprintf(3) 
format string that may havea single xs parameter, which will be given a pathname for the article, relative to the news spool 
directory. The full pathname may be obtained by prefixing the%s in the param fidd by the news spool directory prefix. 
Standard input will be set to the article or /dev/nu11 if the article cannot be opened for some reason. Standard output and 
error will be set to the error log. T he process will run with the user and group ID of the /news/1ib/innd directory. innd will 
try to avoid spawning a shell if the command has no shad meta-characters; this feature can be defeated by appending a 
semicolon to the end of the command. The full pathname of the program to be run must be specified; for security, PATH is 
not searched. 


If the entry is the target of a funnel, and if the we flag is used, then a single asterisk may be used in theparam fidd whee it 
will be replaced by the names of the sites that fed into the funnd.. If the entry isnot a funn, or if thew flag is not used, 
then the asterisk has no special meaning. 
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Flushing a sitefed by a program does no action. 


When asite is fed by achanne or explode, the param field names the process to start. Again, the full pathname of the process 
must be given. W hen thesite is to receive an article, the process receives a line on its standard input telling it about the 
article. Standard output and error and the user and group ID of the all subprocess are set as for a program fead. If the process 
exits, it will be restarted. If the process cannot be started, the server will spool input to afilenamed /news/spool/out.going/ 
sitename. It will then try to start the process some time later. 


W hen asite fed by a channél or exploder is flushed, the server closes down its end of the pipe. Any pending data that has not 
been written will be spooled; see the description of thes flag. N o signal is sent; it isup to the program to notice EOF on its 
standard input and exit. T he server then starts a new process. 


Exploders are a superset of channd feeds. In addition to channd behavior, exploders can be sent command lines. T hese lines 
start with an exclamation point, and thar interpretation is up to the exploder. The following messages are generated 
automatically by the serve: 


newgroup group 
rmgroup group 
flush 

flush site 


T hese messages are sent when the ctlinnd command of the same name is received by the server. In addition, the send 
command can be used to send an arbitrary command line to the exploder child-process. T he primary exploder is buffchan(8). 


Funnel feeds provide a way of merging several site entries into a single output stream. For a site feeding into afunna,, the 
param field names the actual entry that does the feeding. 


For more details on setting up different types of news feeds, see the INN installation manual. 


EXAMPLES 


## Initial subscription list and our distributions. 
ME:*,!junk,!foo.*/world,usa,na,ne,foo,ddn,gnu, inet\ 


## Feed all moderated source postings to an archiver 
source-archive!:!*,comp.sources.*\ 

:Tp,Nm:/usr/local/bin/archive %s 

## Watch for big postings 

watcher! :*\ 

:Tc,Wbnm\ 

sexec awk '$1 > 1000000 { print "BIG", $2, $3 }' >/dev/console 
## A UUCP feed, where we try to keep the "batching" between 4 and 1K. 
ihnp4: /world,usa,na,ddn,gnu\ 

:Tf Wb ,B4096/1024: 

## Usenet as mail; note ! in funnel name to avoid Path conflicts. 
## Can't use ! in "fred" since it would like look a UUCP address. 
fred: !*,comp.sources.unix ,comp.sources.bugs\ 

:Tm:mailer! 
barney@bar.com:!*,news.software.nntp,comp.sources.bugs\ 
:Tm:mailer! 

mailer!:!*\ 

:W*,Tp:/usr/ucb/Mail -s "News article" * 

## NNTP feeds fed off-line via nntpsend or equivalent. 
feed1::Tf,Wnm:feed1.domain.name 

peer. foo.com:foo.*:Tf,Wnm:peer.foo.com 

## Real-time transmission. 

mit.edu: /world,usa,na,ne,ddn,gnu, inet\ 

:Tc,Wnm:/nntplink -i stdin mit.edu 

## Two sites feeding into a hypothetical NNTP fan-out program: 
nic.near.net:\ 

:Tm:nntpfunnel1 


newslog 


uunet.uu.net/uunet: !ne.*/world,usa,na,foo,ddn, gnu, inet\ 
:Tm:nntpfunnel1 

nntpfunnel1:!*\ 

:Tc,Wmn*: /nntpfanout 

## A UUCP site that wants comp.* and moderated soc groups 
uucpsite!comp:!*,comp.*/world,usa,na, gnu\ 

:Tm:uucpsite 

uucpsite!soc:!*,soc.*/world,usa,na,gnu\ 

:Tm,Nm:uucpsite 

uucpsite:!*\ 

:Tf Wb: /usr/spool/batch/uucpsite 


The last two sets of entries show how funnd feeds can be used. For example, the nntpfanout program would receive lines like 
the following on its standard input: 





<123@litchi.foo.com> comp/sources/unix/888 nic.near.net uunet.uu.net 
<124@litchi.foo.com> ne/general/1003 nic.near.net 


Because the UUCP funnd isonly destined for one site, the asterisk is not needed and entries like the following will be 
written into the file: 


<qwe#37x@snark.uu.net>comp/society/folklore/3 
<123@litchi.foo.com> comp/sources/unix/888 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


active(5), buffchan(8), ctlinnd(8), innd(8), wildmat(3) 


newslog 


newslog— D escription of Usenet log files. 


DESCRIPTION 


M ost log files created by U senet programs reside in the /var/1log/news directory and havea .1og extension. Several versions 
are usually kept with an additional extension such as .1, .2, and so on; the higher the number, the older the log. T he older 
versions are compressed. 


The scanlogs script and related utilities (see news1og(8)) are responsible for rotating and compressing these files. 


Some log files always have data, others only have data if thereis aproblem, and others are only created if a particular 
program is used or configuration parameter is set. The innstat script (See news1og(8)) monitors the size of all log files. 


The following files will only accumulate data under the direction of contro1.ct1(5): 
control.log, miscctl.log, newgroup.1log, rmgroup.log, unwanted.1log 


In order to create these files, the message and action fields of control.ct1 should be chosen from the following table: 





M essage Action M eaning 

all log=miscct1 Log all messages by default 
default log=miscct1 Log unknown messages 
newgroup doit=newgroup Create group and log message 
newgroup log=newgroup Log message 


continues 
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M essage Action M eaning 

rmgroup doit=rmgroup Remove group and log message 
rmgroup log=rmgroup Log message 

“other” doit=miscctl Log and process the message 
“other” log=miscct1l Log message 





Here, “other” refersto any other control message such as: 


checkgroups ihave sendme sendsys senduuname version 


The following isa list of log files. 


control.log 


errlog 


expire.log 


miscctl.log 


newgroup. log 


news 


news.crit 


news.err 


news.notice 


nntpsend. log 
rmgroup. log 


unwanted. log 


This file maintains a count of the number of newgroup and rmgroup control messages seen for 
each newsgroup. The count is of the number of control messages with identical arguments, 
regardless of whether they were actually processed. All control arguments, including invalid 
ones, are counted. T his fileis updated by tally.contro1, which isinvoked by scanlogs if 
either the newgroup Or rmgroup logs exist. T his file is not rotated. 

This file contains the standard output and standard error of any program spawned by 
innd(8). The most common programs are the control-message handlers found in /news/bin/ 
control. This file should be empty. Scanlogs will print the entire contents of this log file if it 
is non-empty. 

By default, when news.daily is going to expire old news articles, it writes the date to this 
file, followed by any output from expire(8) and the ending date All lines but the first are 
indented four spaces. 

When control.ct1 is configured as described above all control messages except newgroup 
and rmgroup are appended to thisfile by writelog. T here will be a summary line describing 
the message and the action taken, followed by the article indented by four spaces and a 
blank line. 

When control.ct1 is configured as described above, all newgroup messages are appended to 
this file using the same format as for miscct1.1og. 

This file logs articles received by innd. scanlogs summarizes the rected articles reported in 
thisfile 

All critical error messages issued by innd are appended to this file via sys1og(3). T hislog file 
should be empty. scanlogs will print the entire contents of this log file if it is non-empty. 
You should have the following line in your syslog. cont(5) file 

news.crit /var/log/news/news.crit 

All major error messages issued by innd are appended to thisfile via syslog. T his log file 
should be empty. scanlogs will print the entire contents of this log file if it is non-empty. 
You should have the following linein your sysiog.con¢ file 

news.err /var/log/news/news.err 

All standard error messages and status messages issued by innd are appended to this file via 
syslog. scanlogs uses the awk(1) script innlog.awk to summarize this file You should have 
the following line in your syslog. cont file: 

news.notice /var/log/news/news.notice 

The nntpsend(8) programs appends all status messages to this file. 

When control.ct1 is configured as described previously, all rmgroup messages are appended 
to this file using the same format as for miscct1.1og. 

This log maintains a count of the number of articles that were rejected because they were 
posted to newsgroups that do not exist at the local site This file is updated by 
tally.unwanted and maintained in reverse numeric order (the most popular rejected group 
first). This file is not rotated. 


HISTORY 


Written by Landon Curt N oll (chongo@toad.com) and Rich $alz (rsalzeuunet.uu.net) for |nterN etN ews. 


SEE ALSO 


control.ct1(5), ctlinnd(8), expire(8), innd(8), news.daily(8), nntpsend(8), newslog(8) 


nfs 


nfs— NFS fstab format and options. 


SYNOPSIS 


/etc/fstab 


DESCRIPTION 


The fstab file contains information about which filesystems to mount where and with what options. For N FS mounts, it 
contains the server name and exported server directory to mount from, the local directory that is the mount point, and the 
N FS-specific options that control the way the filesystem is mounted. H ere is an example from an /etc/fstab file from an 
NFS mount. 


server:/usr/local/pub /pub nfs rsize=8192,wsize=8192,timeo=14, intr 


OPTIONS 


rsize=n The number of bytes N FS uses when reading files from an NFS server. The default value is 
dependent on thekernd|, currently 1024 bytes. (H owever, throughput is improved greatly by 
asking for rsize=8192.) 

wsize=n Thenumber of bytes N FS uses when writing files to an N FS server. The default value is 
dependent on the kernal, currently 1024 bytes. (H owever, throughput is improved greatly by 
asking for wsize=8192.) 

timeo=n The value in tenths of asecond beforesending the first retransmission after an RPC time 
out. The default value is 7 tenths of a second. After the first time-out, the timeout is 
doubled after each successive time-out until a maximum timeout of 60 seconds is reached 
or the nnough retransmissions have occurred to cause a major timeout. Then, if the 
filesystem is hard mounted, each new time-out cascade restarts at twice the initial value of 
the previous cascade, again doubling at each retransmission. The maximum time-out is 
always 60 seconds. Better overall performance may be achieved by increasing the time-out 
when mounting on a busy network, to a slow server, or through several routers or gateways. 

retrans=n The number of minor time-outs and retransmissions that must occur before a major time. 
out occurs. T he default is3 timeouts. W hen a major time-out occurs, the file operation is 
either aborted or a “server not responding” message is printed on the console 


acregmin=n Theminimum time in seconds that attributes of a regular file should be cached before 
requesting fresh information from a server. T he default is 3 seconds. 

acregmax=n The maximum time in seconds that attributes of a regular file can be cached before 
requesting fresh information from a server. T he default is 6a seconds. 

acdirmin=n Theminimum time in seconds that attributes of a directory should be cached before 
requesting fresh information from a server. T he default is 30 seconds. 

acdirmax=n The maximum time in seconds that attributes of a directory can be cached before requesting 
fresh information from a server. T he default is 6a seconds. 

actimeo=n Using actimeo sets all of acregmin, acregmax, acdirmin, and acdirmax to the same value. T here 


is no default value. 
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retry=n 


namlen=n 
port=n 


mountport=n 
mounthost=n ame 


mountprog=n 
mountvers=n 
nfsprog=n 


nfsvers=n 
bg 


fg 
soft 


hard 


intr 


posix 


nocto 


noac 


tcp 


udp 


FILES 


/etc/fstab 


The number of times to retry a backgrounded N FS mount operation before giving up. The 
default value is 10000 times. 

When an NFS server does not support version 2 of the RPC mount protocol, this option 
can be used to specify themaximum length of a filename that is supported on the remote 
filesystem. T his is used to support the PO SIX pathconf functions. The default is 255 
characters. 

The numeric value of the port to connect to the NFS server on. If the port number isa (the 
default) then query the remote host’s port mapper for the port number to use If the renote 
host's N FS daemon is not registered with its port mapper, the standard N FS port number 
2049 is used instead. 

The numeric value of the mounta port. 

The name of the host running mountd. 

Use an alternate RPC program number to contact the mount daemon on the remote host. 
This option is useful for hosts that can run multiple N FS servers. T he default valueis 
100005, which is the standard RPC mount daemon program number. 

Use an alternate RPC version number to contact the mount daemon on the remote host. 
This option is useful for hosts that can run multiple N FS servers. T he default valueis 
version 1. 
Use an alternate RPC program number to contact the N FS daemon on the renote host. 
This option is useful for hosts that can run multiple N FS servers. T he default valueis 
100003, which is the standard RPC N FS daanon program number. 

Use an alternate RPC version number to contact theN FS daemon on the remote host. This 
option is useful for hosts that can run multiple N FS servers. T he default value is version 2. 
If the first NFS mount attempt times out, continue trying the mount in the background. 
The default is to not to background the mount on time-out but to fail. 

If the first NFS mount attempt times out, fail immediately. T his is the default. 

If an N FS file operation has a major time-out, then report an I/O error to the calling 
program. T he default is to continue retrying N FS file operations indefinitely. 

If an N FS file operation has a major time-out, then report “server not responding” on the 
console and continue retrying indefinitdy. T his is the default. 

If an N FS file operation has a major time-out and it is hard mounted, then allow signals to 
interrupt the file operation and cause it to return ErnTr to the calling program. The default 
is to not allow file operations to be interrupted. 

Mount theN FS filesystem using PO SIX semantics. This allows an N FS filesystem to 
properly support the PO SIX pathconf command by querying the mount server for the 
maximum length of a filename To do this, the renote host must support version 2 of the 
RPC mount protocol. M any NFS servers support only version 1. 

Suppress the retrieval of new attributes when creating a file. 

Disable all forms of attribute caching entirely. T his extracts a server performance penalty, 
but it allows two different N FS clients to get reasonably good results when both clients are 
activdy writing to acommon filesystem on the server. 

Mount theN FS filesystem using the TCP protocol instead of the default UDP protocol. 

M any NFS severs only support UDP. 

Mount theN FS filesystem using the UDP protocol. Thisis the default. All the non-value 
options have corresponding nooption forms. For example, nointr means don't allow file 
operations to be interrupted. 
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SEE ALSO 


fstab(5), mount(8), umount(8), exports(5) 


AUTHOR 


Rick Sladkey (jrs@world.std.com) 


BUGS 


The bg, fg, retry, posix, and nocto options are parsed by mount but currently are silently ignored. The tcp and namien 
options are implemented but are not currently supported by the Linux kernel. The umount command should notify the server 
when an NFS filesystem is unmounted. 


Linux 0.99, 20 N ovember 1993 


nnrp.access 


nnrp.access— Access file for on-campus N NTP sites. 


DESCRIPTION 


Thefile /news/lib/nnrp.access specifies the access control for those N NTP sites that are not handled by the main 
InterN tN ews daemon inna(8). The nnrpd(8) server reads it when first spawned by innd. 


Comments begin with anumber sign (#) and continue through the end of the line Blank lines and comments are ignored. 
All other lines should consist of five fields separated by colons: 


hosts :perms :username:password:patterns 


The first field is a wildmat(3)-style pattern specifying the names or Internet address of a set of hosts. Before a match is 
checked, the client’s hostname (or its Internet address if gethostbyaddr(3) fails) is converted to lowercase. Each line is 
matched in turn, and the last successful match is taken as the correct one. 


The second fidd is a set of letters specifying the permissions granted to the client. Theperms should bechosen from the 
following set: 


R Theclient can retrieve articles 
P Theclient can post articles 


The third and fourth fidds specify theusername and password that the client must use to authenticate themselves before the 
server will accept any articles. N ote that no authentication (other than a matching entry in this file) is required for 
newsreading. If they are enpty, then no password is required. Whitespace in these fields will result in the client being unable 
to properly authenticate thanselves and may be used to disable access. 


The fifth field isa set of patterns identifying the newsgroups that the client is allowed to access. Thepatterns areinterpreted 
in the same manner as the newsfeeds(5) file. T he default, however, denies access to all groups. 


The access file is normally used to provide host-level access control for reading and posting articles. T here are times, however, 
when thisis not sufficient and user-level access control is needed. Whenever an NNTP authinto command is used, the nnrpd 
server rereads this file and looks for a matching username and password. If the local newsreaders are modified to send the 
authinfo command, then all host entries can have no access and specific users can be granted the appropriateread and post 
access. For example: 


## host: perm:user:pass: groups 

## Default is no access. 

tro-mo- 2 -no- :!* 

## FOO hosts have no password, can read anything. 
-foo.com:Read Post:::* 

## A related workstation can't access FOO newsgroups. 
lenox.foo.net:RP:martha:hiatt:*,!foo.* 
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If the file contains passwords, it should not be world-readable 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


inna(8), newsfeeds(5), nnrpd(8), wildmat(3) 


nntpsend.ctl 


nntpsend.ct1— List of sites to feed via nntpsend. 


DESCRIPTION 
The file /news/1lib/nntpsend.ct1 specifies the default list of sites to be fed by nntpsend(8). 


Comments begin with a number sign (#) and continue through the end of the line Blank lines and comments are ignored. 
All other lines should consist of four fields separated by a colon. 


The first field is the name of the site as specified in the newsfeeds(5) file 
The second fidd should be the hostname or IP address of the remote site. 


The third fidd, if non-enpty, specifies the default tail truncation 9ze of site’s batchfile. T his is passed to shrinkfile asthe -s 
flag. If this field isempty, no truncation is performed. 


The fourth field specifies some default flags passed to innxmit(8). T heflag -a is always given to innxmit and need not appear 
here If no -t timeout flag is given in this fidd and on the nntpsend command line, -t 180 will be given to innxmit. 


HISTORY 


Written by Landon Curt N oll (chongo@toad.com) for InterN e&tN ews. 


SEE ALSO 


innxmit(8), newsfeeds(5), nntpsend(8), trunc(1) 


nologin 
nologin— Prevent usual users from logging into the system. 


DESCRIPTION 


If the file /etc/nologin exists, login(1) will allow access only to root. O ther users will be shown the contents of this file and 
their logins refused. 


FILES 


/etc/nologin 


SEE ALSO 


login(1), shutdown(8) 
Linux, 29 D canbe 1992 


overview. fmt 


overview. fmt— Format of news overview database. 


DESCRIPTION 


The file /news/1ib/overview. fmt specifies the organization of the news overview database. Blank lines and lines beginning 
with anumber sign (#) are ignored. T heorder of linesin this file is important; it determines the order in which the fidds will 
appear in the database 


M ost lines will consist of an article header name, optionally followed by a colon. A trailing set of lines can have the word full 
appear after the colon; this indicates that the header should appear as well as its value. 


If this file is changed, it is usually necessary to rebuild the existing overview database using expireover(8) after removing all 
existing overview files. 

The default file, show here, is compatible with G eoff C ollyer’s nov package: 
Subject: 

From: 

Date: 

Message-ID: 

References: 

Bytes: 

Lines: 

## Some newsreaders get better performance if Xref is present 
#Xref:full 


HISTORY 


Written by Rich $alz (rsalze@uunet.uu.net) for InterN €@tN ews. Intended to be compatible with the nov package written by 
Geoff Collyer (geoffeworld.std.com). 


passwd 


passwd— Password file. 


DESCRIPTION 


passwd isan ASCII file that contains a list of the system's users and the passwords they must use for access. T he password file 
should have general read permission (many utilities, such as 1s(1), use it to map user 1D sto usernames) but write access only 
for the superuser. 

In the good old days, there was no great problen with this general read permission. Everybody could read the encrypted 
passwords, but the hardware was too slow to crack a well-chosen password, and moreover, the basic assumption used to be 
that of a friendly user community. T hese days, many people run some version of the shadow password suite, where /etc/ 
passwd has *Sinstead of passwords, and the encrypted passwords are in /etc/shadow, which is readable by root only. 

When you create a new login, leave the password field empty and use passwa(1) to fill it. A star (*) in the password fidd 
means that this user cannot log in via login(1). 

There is one entry per line, and each line has the format: 


login_name:passwd:UID:GlD:user_name:directory:shel 


The field descriptions are 


|ogin_name The name of the user on the system. 

password The encrypted optional user password. 

UID The numerical user ID. 

GID The numerical group ID for this user. 

user_name The (optional) comment field (often a full username). 
directory Theuser’s $Home directory. 


shell The program to run at login (if empty, use /bin/sh). 
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NOTE 
If your root file system ison /dev/ram, you must save a changed password fileto your root filesystem floppy before you shut 
down the system and check the access rights. If you want to create user groups, their GID s must be equal and there must be 
an entry in /etc/group, or no group will exist. 


FILES 


/etc/passwd 


SEE ALSO 
passwd(1), login(1), group(5), shadow(5) 
Linux, 24 July 1993 


passwd. nntp 


passwd.nntp— Passwords for connecting to renote N NTP servers. 


DESCRIPTION 


Thefile /news/1ib/passwd.nntp contains host-name password triplets for use when authenticating client programs to NNTP 
servers. T his file is normally interpreted by the nnTPsend- password routinein 1ibinn(3). Blank lines and lines beginning with 
anumber sign (#) are ignored. All other lines should consist of three or fields separated by colons: 


host :name :password 
host :name :password:style 


The first field is the name of ahost and is matched in a case-insensitive mannex. T he second field is a username, and the 
third isa password. T he optional fourth field specifies the type of authentication to use The default is authinfo, which 
means that NNTP authinfo commands are used to authenticate to the renote host. If either the username or password are 
empty, then the rdated command will not be sent. (The authinfo command isacommon extension to RFC 977.) For 
example: 


## UUNET needs a password, MIT doesn't. 
mit.edu:bbn: :authinfo 
uunet.uu.net:bbn:yoyoma: authinfo 


This file should not be world-readable. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


innd(8), libinn(3) 


pbm 


pbm— Portable bitmap file format. 


DESCRIPTION 


The portable bitmap format is a lowest common denominator monochrome file format. It was originally designed to make it 
reasonable to mail bitmaps between different types of machines using the typical stupid network mailers we have today. N ow 
it serves as the common language of a large family of bitmap conversion filters. T he definition is as follows: 


A “magic number” for identifying the file type. A pbm file's magic number is the two characters P1. 


W hitespace (blanks, T abs, CRs, LFs). 

A width, formatted as ASCII characters in decimal. 

W hitespace. 

A height, again in ASCII decimal. 

W hitespace. 

Width * height bits, each either 1 or @, starting at the top-left corner of the bitmap, proceeding in normal English reading 
order. 

The character 1 means black; @ means white. 

Whitespace in the bits section is ignored. 

Characters from a# to the next end-of-line are ignored (comments). 
No line should be longer than 70 characters. 


H ereisan example of asmall bitmap in this format: 
P4 


# feep.pbm 

24 7 
OH9HCHHHHHHHDHHHXOHHHOHHHH0O 
011110011110011110011110 
010000010000010000010010 
011100011100011100011110 
010000010000010000010000 
010000011110011110010000 
O898HHHHHHHHHHHOHHHOHHHBOO 


Programs that read this format should be as lenient as possible, accepting anything that looks renotdy like a bitmap. 
There is also a variant on the format, available by setting the rawsrTs option at compile time This variant is different in the 
following ways: 

The “magic number” is p4 instead of P1. 

The bits are stored eight per byte, high bit first and low bit last. 


No whitespace is allowed in the bits section, and only a single character of whitespace (typically a newline) is allowed after 
the height. 
The files are eight times smaller and many times faster to read and write 


SEE ALSO 


atktopbm(1), brushtopbm(1), cmuwmtopbm(1), g3topbm(1), gemtopbm(1), icontopbm(1), macptopbm(1), mgrtopbm(1), pi3topbm(1), 
xbmtopbm(1), yomtopbm(1), pbmto10x(1), pnmtoascii(1), ppmtoatk(1), pbmtobbnbg(1), pbmtocmuwm(1), ppmtoepson(1), ppmtog3(1), 
pbmtogem(1), pomtogo(1), pbmtoicon(1), pbmtolj(1), pbmtomacp(1), pomtomgr(1), pbmtopi3(1), pomtoplot(1), pomtoptx(1), 
pbmtox10bm(1), pbmtoxbm(1), pomtoybm(1), ppmtozinc(1), pbmlife(1), ppmmake(1), pbmmask(1), pbmreduce(1), pbmtext(1), 
pomupe(1), pnm(5), pgm(5), ppm(5) 


AUTHOR 
Copyright 1989, 1991 by J ef Poskanzer. 
27 September 1991 


pgm 


pgm— Portable graymanp file format. 
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DESCRIPTION 
The portable graymap format is a lowest common denominator grayscale file format. T he definition is as follows: 
A “magic number” for identifying the file type. A pgm file's magic number is the two characters p2. 


W hitespace (blanks, T abs, CRs, LFs). 

A width, formatted as ASCII characters in decimal. 
W hitespace. 

A height, again in ASCII decimal. 

W hitespace. 

Themaximum gray value, again in ASCII decimal. 
W hitespace. 





Width * height gray values, each in ASCII decimal, between @ and the specified maximum value, separated by whitespace, 
starting at the top-left corner of the graymap, proceeding in normal English reading order. A value of means black, and the 
maximum value means white. 


Characters from a# to the next end-of-line are ignored (comments). 
No line should be longer than 70 characters. 


H ereisan example of a small graymap in this format: 


P2 

# feep.pgm 

24 7 

15 

OQH9HCHHHHHHXDHHHHOHDHHHOHXOHO00 
0333300777700 11 11 1111 00 15 1515 15 0 
03000007000001100000 15 0 0 150 
0333000777000 11 11 1100 0 15 15 15 150 
023000007000001100000150000 
0300000777700 11 11 111100150000 
OH9HHHHHHHHDHHHXOHHHHOHHHB00 


Programs that read this format should be aslenient as possible accepting anything that looks remotely like a graymap. 


Thereis also a variant on the format, available by setting the rawsrTs option at compile time This variant is different in the 
following ways: 

The “magic number” is Ps instead of P2. 

The gray values are stored as plain bytes, instead of ASCII decimal. 


No whitespace is allowed in the grays section, and only a single character of whitespace (typically a newline) is allowed after 
the maxval. 


The files are smaller and many times faster to read and write 
N ote that this raw format can only be used for maxvals less than or equal to 255. If you use the pgm library and try to writea 
file with a larger maxval, it will automatically fall back on the slower but more gneral plain format. 

SEE ALSO 


fitstopgm(1), fstopgm(1), hipstopgm(1), 1ispmtopgm(1), psidtopgm(1), rawtopgm(1), pgmbentley(1), pgmcrater(1), pgmedge(1), 
pgmenhance(1), pgmhist(1), pgmnorm(1), pgmoil(1), pgmramp(1), pgmtexture(1), pgmtofits(1), pgmtofs(1), pgmtolispm(1), 
pgmtopbm(1), pnm(5), pom(5), ppm(5) 


AUTHOR 
Copyright 1989, 1991 by Jef Poskanzer. 
12 N ovenber 1991 


pnm 


pnm— Portable anymap file format. 


DESCRIPTION 


The pnm programs operate on portable bitmaps, graymaps, and pixmaps produced by the pbm, pgm, and ppm segments. T here is 
no file format associated with pnm itself. 


SEE ALSO 


anytopnm(1), rasttopnm(1), tifftopnm(1), xwdtopnm(1), pnmtops(1), pnmtorast(1), pnmtotift(1), pnmtoxwd(1), pnmarith(1), 
pnmcat(1), pnmconvol(1), pnmcrop(1), pnmcut(1), pnmdepth(1), pnmenlarge(1), pnmfile(1), pnmflip(1), pnmgamma(1), pnmindex(1), 
pnminvert(1), pnmmargin(1), pnmnoraw(1), pnmpaste(1), pnmrotate(1), pnmscale(1), pnmshear(1), pnmsmooth(1), pnmtile(1), 
ppm(5), pgm(5), pbm(5) 


AUTHOR 
Copyright 1989, 1991 by J ef Poskanzer. 
27 September 1991 


ppm 


ppm— Portable pixmanp file format. 


DESCRIPTION 
The portable pixmap format isa lowest common denominator color image file format. T he definition is as follows: 
A “magic number” for identifying the file type. A ppm file's magic number is the two characters p3. 


W hitespace (blanks, T abs, CRs, LFs). 

A width, formatted as ASCII characters in decimal. 

W hitespace. 

A height, again in ASCII decimal. 

W hitespace. 

The maximum color-component value, again in ASCII decimal. 
W hitespace. 





Width * haght pixds, each three ASCI| decimal values between 0 and the specified maximum value, starting at the top-left 
corner of the pixmap, proceeding in normal English reading order. The three values for each pixd represent red, green, and 
blue; a value of o means that color is off, and the maximum value means that color is maxed out. 

Characters from a# to the next end-of-line are ignored (comments). 

No line should be longer than 70 characters. 


H ereisan example of a small pixmap in this format: 


P3 

# feep.ppm 

44 

15 
000000000150 15 
0000157000000 
0000000157000 
15 015000000000 


Programs that read this format should be aslenient as possible accepting anything that looks remotely like a pixmap. 
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There is also a variant on the format, available by setting the raws1Ts option at compile time This variant is different in the 
following ways: 


The “magic number” is Pe instead of P3. 
The pixel values are stored as plain bytes, instead of ASCII decimal. 


W hitespace is not allowed in the pixels area, and only a single character of whitespace (typically anewline) is allowed after 
the maxval. 


The files are smaller and many times faster to read and write. 


N ote that this raw format can only be used for maxvals less than or equal to 255. If you use the ppm library and try to write a 
file with a larger maxval, it will automatically fall back on the slower but more gneral plain format. 


SEE ALSO 


giftoppm(1), gouldtoppm(1), ilbmtoppm(1), imgtoppm(1), mtvtoppm(1), pextoppm(1), pgmtoppm(1), pittoppm(1), picttoppm(1), 
pjtoppm(1), qrttoppm(1), rawtoppm(1), rgb3toppm(1), sldtoppm(1), spctoppm(1), sputoppm(1), tgatoppm(1), ximtoppm(1), 
xpmtoppm(1), yuvtoppm(1), ppmtoacad(1), ppmtogit(1), ppmtoicr(1), ppmtoilbm(1), ppmtopcex(1), ppmtopgm(1), ppmtopit(1), 
ppmtopict(1), ppmtopj(1), ppmtopuzz(1), ppmtorgb3(1), ppmtosixel(1), ppmtotga(1), ppmtouil(1), ppmtoxpm(1), ppmtoyuv(1), 
ppmdither(1), ppmforge(1), ppmhist(1), ppmmake(1), ppmpat(1), ppmquant(1), ppmquantal1(1), ppmreliet(1), pnm(5), pgm(5), pbm(5) 


AUTHOR 
Copyright 1989, 1991 by Jef Poskanzer. 
27 September 1991 


/proc 


/proc— Process information pseudo-filesystem. 


DESCRIPTION 


/proc is apseudo-filesysten that is used as an interface to kernd data structures rather than reading and interpreting /dev/ 
kmem. M ost of it is read-only, but some files allow kernd variables to be changed. 


The following outline gives a quick tour through the /proc hierarchy. 


[number ] There is a numerical subdirectory for each running process; the subdirectory is named by the 
process|!D. Each contains the following pseudo-files and directories. 
cmdline This holds the complete command line for the process, unless the whole process has been swapped 


out or unless the process is a zombie In eather of these later cases, there isnothing in this file: T hat 
is, aread on thisfile will return as having read 0 characters. This file is null-terminated but not 
newline-terminated. 

cwd This is alink current working directory of the process. To find out the cwa of process 20, for 
instance, you can do this: cd /proc/20/cwd; /bin/pwd. N ote that the pwd command is often a shell 
built in and might not work propelly in this context. 

environ This file contains the environment for the process. The entries are separated by null characters, and 
there may be anull character at the end. Thus, to print out the environment of process 1, you 
would do 
(cat /proc/1/environ; echo) {| tr "\@00" "\n" 
For areason why one should want to do this, see 1i10(8). 

exe A pointer to the binary that was executed and appears as a symbolic link. readlink(2) on the exe 
special file returns a string in the format: 
[device]:inode 
For example, [@301]:1502 isinode 1502 on device major 03 (IDE, MFM, and so on drives), minor 


/proc 1175 


01 (first partition on the first drive). Also, the symbolic link can be dereferenced normally; 
attempting to open exe will open the executable You can even type /proc/ {number ] /exe to run 
another copy of the same process as [number ]. 


fina(1) with the -inum option can be used to locate the file 


fd Thisis a subdirectory containing one entry for each file that the process has open, named by its file 
descriptor, and that is asymbolic link to the actual file (as the exe entry does). Thus, 0 is standard 
input, 1 standard output, 2 standard error, and so on. 


Programs that will take a filename but will not take the standard input and that write to a file but 
will not send ther output to standard output can be effectively foiled this way, assuming that -i is 
the flag designating an input file and -o isthe flag designating an output file: 


foobar -i /proc/self/fd/0 -o /proc/self/fd/1... 


and you havea working filter. N ote that this will not work for programs that seek on thar files 
because the filesin the ta directory are not seexable 


/proc/self/fd/N iSapproximatdy the same as /dev/fd/n in someUN IX and UNIX-like systems. 
M ost Linux makepev scripts symbolically link /dev/fa to /proc/self/fd, in fact. 


maps A file containing the currently mapped memory regions and their access permissions. 
The format is 





address perms offset dev inode 
00000000 -0002F000 r-X- 00000400 03:03 1401 
0002f 000 - 00032000 rwx-p 0002f400 03:03 1401 
00032000 -0005b000 rwx-p 00000000 00:00 () 
60000000 -60098000 rwx-p 00000400 03:03 215 
60098000 -600c7000 rwx-p 00000000 00:00 t) 

bf ffa000 -c0000000 rwx-p 00000000 00:00 () 





address iSthe address space in the process that it occupies. perms is aset of permissions: r =read, w 
=write, x =execute, s = shared, p =private (copy on write). 

offset isthe offset into the file/whatever, dev isthe device (major: minor), andi node isthe inode 
on that device. a indicates that no inode is associated with the memory region, as the case would be 
with bss. 


mem This is not the same as the mem (1,1) device, despite the fact that it has the same device numbers. 
The /dev/mem device is the physical menory before any address translation is done, but themem file 
here is the memory of the process that accesses it. This cannot be mmap(2)ed currently, and will not 
be until a general mmap(2) is added to the kernal. (This might have happened by the time you read 
this.) 

mmap Directory of maps by mmap(2) that are symbolic links such as exe, fd/*, and so on. N ote that maps 
includes a superset of this information, So /proc/*/mmap should be considered obsolete. 
0 is usually libc.so.4. 
/proc/*/mmap was removed in Linux kernd version 1.1.40. (It really was obsolete!) 

root UNIX and Linux support the idea of a pe-process root of the filesystem, set by the chroot(2) 
system call. root points to the filesystem root and behaves as exe, fd/*, and so on do. 

stat Status information about the process. This is used by ps(1). Thefields, in order, with their proper 
scanf(3) format specifiers, are 
pid %d The process 1D . 
comm %s The filename of the executable in parentheses. T his is visible whether or not 

the executable is swapped out. 
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state %c 


ppid %d 
pgrp %d 
session %d 
tty %d 
tpgid %d 


flags %u 


minflt %u 


cminflt %u 


majflt %u 


cmajflt %u 
utime %d 
stime %d 


cutime %d 


cstime %d 


counter %d 


priority %d 


timeout %u 


itrealvalue %u 


starttime %d 
vsize %u 


rss %u 


rlim %u 
startcode %u 
endcode %u 
startstack %u 


kstkesp %u 


kstkeip %u 
signal %d 
blocked %d 


One character from the string rspzt wherer is running, s is Sleeping in an 
interruptible wait, p issleeping in an uninterruptible wait or swapping, z is 
zombie, and T is traced or stopped (on a signal). 

The PID of the parent. 

The process group ID of the process. 

The session ID of the process. 

The tty the process uses. 


The process group ID of the process that currently owns the tty that the 
process is connected to. 


The flags of the process. Currently, every flag has the math bit set because 
ert@.s checks for math emulation, so this isnot included in the output. This 
is probably abug because not every process isacompiled C program. The 
math bit should be a decimal 4, and the traced bit is decimal 10. 


Thenumber of minor faults the process has made, those that have not 
required loading amemory page from disk. 


The number of minor faults that the process and its children have made 


Thenumber of major faults the process has made, those that have required 
loading amemory page from disk. 


Thenumber of major faults that the process and its children have made. 
Thenumber of jiffies that this process has been scheduled in user mode. 
The number of jiffies that this process has been scheduled in kend mode. 


Thenumber of jiffies that this process and its children have been scheduled 
in user mode 


Thenumber of jiffies that this process and its children have been scheduled 
in kernel mode. 


The current maximum size in jiffies of the process's next timeslice, or what is 
currently left of its current timeslice if it is the currently running process. 


The standard nice value plus fifteen. T he value is never negative in the 
kend. 


The time in jiffies of the process's next time-out. 


The time (in jiffies) before the next stcacrm is sent to the process due to an 
interval timer. 


Time the process started in jiffies after system boot. 
Virtual memory size. 


Resident set size N umber of pages the process hasin real memory, minus 3 
for administrative purposes. T his is just the pages that count toward text, 
data, or stack space. T his does not include pages that have not been denand- 
loaded in or that are swapped out. 


Current limit in bytes on the rss of the process (usually 2,147, 483,647). 
The address above which program text can run. 

The address bed ow which program text can run. 

The address of the start of the stack. 


The current value of esp (32-bit stack pointer), as found in the kernel stack 
page for the process. 


The current erp (32-bit instruction pointer). 
The bitmap of pending signals (usually 0). 
The bitmap of blocked signals (usually 0, 2 for shells). 
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sigignore %d The bitmap of ignored signals. 
sigcatch %d The bitmap of catched signals. 
wehan %u This is the “channel” in which the process is waiting. This is the address of a 


system call and can be looked up in aname list if you need a textual name (If 
you have an up-to-date /etc/psdatabase, then try ps -1 to se thewcuan field 





in action.) 

cpuinfo This is acollection of CPU and system architecture dependent items; for each supported architec- 
ture is a different list. The only two common entries are cpu, which istheC PU currently in use, 
and Bogomips, a system constant that is calculated during kernel initialization. 

devices T et listing of major numbers and device groups. This can be used by makenev scripts for consis 
tency with the kernd. 

dma Thisis alist of the registered ISA DMA (direct memory access) channels in use. 

filesystems A tet listing of the filesystems that were compiled into the kernd. Incidentally, this is used by 
mount(1) to cyclethrough different filesystems when noneis specified. 

interrupts This is used to record the number of interrupts per each IRQ on (at least) the i386 architecture. 
Very easy to read formatting donein ASCII. 

ioports This is alist of currently registered input-output port regions that are in use 

kcore This file represents the physical memory of the system and is stored in the corefile format. With 





this pseudo-file and an unstripped kernel (/usr/src/linux/tools/zSystem) binary, apB can be used 
to examine the current state of any kernel data structures. 
The total length of the file is the size of physical memory (RAM ) plus 4KB. 

kmsg This file can be used instead of the syslog(2) system call to log kernel messages. A process must 
have superuser privileges to read this file and only one process should read this file This file should 
not be read if a syslog process is running that uses the sys1og(2) system call facility to log kernel 


messages. 
Information in this file is retrieved with the amesg(8) program. 

ksyms This holds the kernd exported symbol definitions used by the modules(x) tools to dynamically link 
and bind loadable modules. 

loadavg The load average numbers give the number of jobsin the run queue averaged over 1,5, and 15 
minutes. T hey are the same as the load average numbers given by uptime(1) and other programs. 

malloc This file is only present if CoNFIGDEBUGMALLOC was defined during compilation. 

meminfo This is used by free(1) to report the amount of free and used memory (both physical and swap) on 


the system as wall as the shared memory and buffers used by the kernd. 
It isin the same format as free(1) except in bytes rather than KB. 

modules A text list of the modules that have been loaded by the systen. 

net Various net pseudo-files, all of which give the status of some part of the networking layer. T hese 
files contain ASCII structures and are therefore readable with cat. H owever, the standard 
netstat(8) suite provides much cleaner access to these files. 

arp This holds an ASCII readable dump of the kernd ARP table used for address resolutions. It will 
show both dynamically learned and preprogrammed ARP entries. The format is 





IP address HW type Flags HW address 
10.11.100.129 0x1 0x6 00:20:8A:00:00:5A 
10.11.100.5 0x1 0x2 00:CO:EA:00:00:4E 
44.131.10.6 0x3 Qx2 GW4PTS 





1? address iStherpv4 address of the machine. Theuw type isthe hardware type of the address from 
RFC 826. The flags are the internal flags of the ARP structure (as defined in /usr/include/1inux/ 
if_arp.h) and thew address isthe physical layer mapping for that IP address if it is known. 
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dev 


ipx 
ipx_route 


rarp 


raw 


route 


snmp 


tcp 


udp 


unix 


The dev pseudo-file contains network device status information. This gives the number of received 
and sent packets, the number of errors and collisions, and other basic statistics. T hese are used by 
the ifconfig(8) program to report device status. T he format is 


Inter-| Receive | Transmit 
face jpackets errs drop fifo frame;packets errs drop fifo colls carrier 


lo: 0 ) t) t) t) 2353 0 0 0 ) Q 


ethO: 644324 1 t) t) 1 563770 0 0 0 581 0 


No information. 
No information. 


This file uses the same format as the ARP file and contains the current reverse mapping database 
used to provide rarp(8) reverse address lookup services. If rarp is not configured into the kernel, 
this file will not be present. 

H olds adump of the RAW socket table. M uch of the information is not of use apart from 
debugging. The si value isthe kernal hash slot for the socket; the local_address is the local address 
and protocol number pair. st is theinternal status of the socket. The tx_queue and rx_queue are the 
outgoing and incoming data queue in terms of kernd memory usage. Thetr, tm->when, and rexmits 
fidds are not used by RAW. Theuid field holds the creator euid of the socked. 

No information but looks similar to route(8). 


This file holdsthe ASCII data needed for the IP, ICMP, TCP, and UD P management information 
bases for an snmp agent. As of writing, the TCP mib isincomplete. It should be completed by 1.2.0. 


H olds adump of the TCP socket table. M uch of the information is not of use apart from 
debugging. The si value is the kernal hash slot for the socket; the local_address is the local address 
and port number pair. The remote_address is the remote address and port number pair (if 
connected). st isthe internal status of the socket. The tx_queue and rx_queue are the outgoing and 
incoming data queue in terms of kernel memory usage Thetr, tm->when, and rexmits fields hold 
internal information of the kernel socket state and are only useful for debugging. T he uia field 
holds the creator euid of the socket. 

H olds adump of the UD P socket table. M uch of the information is not of use apart from 
debugging. The si value isthe kernel hash slot for the socked; the 1ocal_address is the local address 
and port number pair. The remote_address is the remote address and port number pair (if 
connected). st isthe internal status of the socket. The tx_queue and rx_queue are the outgoing and 
incoming data queue in terms of kernel memory usage. Thetr, tm->when, and rexmits fields arenot 
used by UDP. The uid fidd holds the creator euid of the socket. The format is 








sl local_address rem_address st tx_queue rx_queue tr rexmits tm->when uid 
1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 


1: 00000000:0801 00000000: 0000 2A 00000000:00000000 00:00000000 6FO00100 O 
1: 00000000:0201 00000000:0000 2A 00000000:00000000 00:00000000 00000000 0 


Lists the UNIX domain sockets present within the system and their status. T he format is 


Num RefCount Protocol Flags Type St Path 
O: 00000002 20000000 20000000 0001 03 
1: 00000001 00000000 00010000 0001 01 /dev/printer 


Num isthe kernel table slot number, RefCount is the number of users of the socket, Protocol is 
currently always 0, and Flags represents the internal kernel flags holding the status of the socked. 
Type is currently always 1 (UNIX domain datagram sockets are not yet supported in the kernel). st 
isthe internal state of the socket and Path isthe bound path (if any) of the socket. 


pei 


scsi 


scsi/scsi 


drivername 


self 


stat 
Cpu 3357 0 4313 1362393 


disk 0000 


page 5741 1808 
swap 1 0 

intr 1462898 
ctxt 115315 
btime 769041601 


sys 


kernel 
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Thisis a listing of all PCI devices found during kernd initialization and their configuration. 

A directory with the SCSI mid-level pseudo-file and various SC SI low-levdl driver directories, 
which contain a file for each SCSI host in this system, all of which give the status of some part 
of the SCSI 10 subsystem. T hese files contain ASCII structures and are therefore readable with 
cat. 

You can also write to some of the files to reconfigure the subsystem or switch certain features on 
or Off. 

Thisisalisting of all SCSI devicesknown to thekernd. T helisting is similar to the one seen 
during bootup. scsi currently supports only the single device command, which allows root to 
add a hot-plugged device to the list of known devices. 

An echo 'scsisingledevice1 @ 5 @'> /proc/scsi/scsi will cause host scsii to scan on SCSI 
channel 0 for adeviceon!ID 5 LUN 0. If there is already a device known on this address or the 
address is invalid, an error will be returned. 


drivername Can currently be NCR53c7xx, aha152x, aha1542, aha1740, aic7xxx, buslogic, eata_dma, 
eata_pio, fdomain, in2000, pas16, qlogic, scsi_debug, seagate, t128, u15-24f, ultrastor, OF 
wd7000. T hese directories show up for all drivers that registered at least one SC SI H BA. Every 
directory contains one file per registered host. Every host-fileisnamed after thenumber the 
host got assigned during initialization. 

Reading these files will usually show driver and host configuration, statistics, and so on. 
Writing to these files allows different things on different hosts. For example, with the latency 
and nolatency commands, root can switch on and off command latency measurement code in 
the eata_dma driver. With the lockup and unlock commands, root can control bus lockups 
simulated by the scsi_debug driver. 

This directory refers to the process accessing the /proc filesystem and isidentical to the /proc 
directory named by the process 1D of the same process. 


kernel/system Statistics, 

The number of jiffies (1/100ths of a second) that the system spent in user mode, user mode 
with low priority (nice), systen mode, and the idle task. The last value should be 100 times the 
second entry in the uptime pseudo-file 

The four disk entries are not implemented at this time I’m not even sure what this should be 
because kerne! statistics on other machines usually track both transfer rate and I/Os per second 
and this only allows for one fidd per drive 


The number of pages the system paged in and the number that were paged out (from disk). 
Thenumber of swap pages that have been brought in and out. 

The number of interrupts received from the systen boot. 

Thenumber of context switches that the system underwent. 

Boot time in seconds since the epoch (January 1, 1970). 

This directory (present since 1.3.57) contains a number of files and subdirectories correspond- 
ing to kernel variables. T hese variables can be read and sometimes modified using the proc 
filesystem and using the sysct1(2) system call. Presently, there are subdirectories kernel, net, 
and vm that each contain more files and subdirectories. 

This contains the files domainname, file-max, file-nr, hostname, inode-max, inode-nr, osrelease, 
ostype, panic, real-root-dev, securelevel, and version, with function fairly clear from the 
name 

The (read-only) file file-nr gives the number of files presently opened. The file file-max gives 
the maximum number of open files the kernel is willing to handle. If 1024 is not enough for 
you, try echo 4096 > /proc/sys/kernel/file-max. 

Similarly, the files inode-nr and inode-max indicate the present and the maximum number of 
inodes. 
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The files ostype, osrelease, and version give substrings of /proc/version. 


The file panic gives r/w access to the kernel variable panic_timeout. If this is zero, the kena will 
loop on apanic; if nonzero, it indicates that the kernel should autoreboot after this number of 





minutes. 
The file securelevel seams rather meaningless at present; root is just too powerful. 

uptime This file contains two numbers: the uptime of the system (seconds) and the amount of time 
spent in idle process (seconds). 

version This string identifies the kernd version that is currently running. For instance: 


Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 


SEE ALSO 
cat(1), find(1), free(1), mount(1), ps(1), tr(1), uptime(1), readlink(2), mmap(2), chroot(2), syslog(2), hier(7), arp(8), 
dmesg(8), netstat(8), route(8), ifcontig(8), procinfo(8) and much more 

CONFORMS TO 


This roughly conforms to a Linux 1.3.11 kernel. Please update this as necessary! Last updated for Linux 1.3.11. 


CAVEATS 


N ote that many strings (the environment and command line) are in the internal format, with subfields terminated by null 
bytes, so you might find that things are more readable if you use od -c Or tr "\o00" "\n" to read them. 


This manual page is incomplete, possibly inaccurate, and is the kind of thing that needs to be updated very often. 


BUGS 


The /proc filesystem may introduce security holes into processes running with chroot(2). For example, if /proc is mounted in 
the chroot hierarchy, achdir(2) to /proc/1/root will return to the original root of the filesystem. This may be considered a 
feature instead of a bug because Linux does not yet support the fchroot(2) call. 


22 July 1996 
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protocols— T he protocols definition file. 


DESCRIPTION 


This file is a plain ASCII file, describing the various D ARPA Interne protocols that are available from the TCP/IP 
subsystem. It should be consulted instead of using the numbers in the ARPA include files or, even worse, just guessing them. 
These numbers will occur in the protocol field of any IP header. 


Keep this file untouched because changes would result in incorrect IP packages. Protocol numbers and names are specified by 
theDDN Network Information C enter. 


Each line is of the following format: 


protocol number aliases ... 


The fields are ddimited by spaces or tabs. Empty lines and lines starting with a hash mark (#) are ignored. Remainder of lines 
are also ignored from the occurrence of a hash mark. 

The field descriptions are 

protocol The native name for the protocol— for example, ip, tcp, Or udp. 

number The official number for this protocol as it will appear within the!P header. 

aliases O ptional aliases for the protocol. 


rcsfile 


This file might be distributed over a network using a network-wide naming service such as Yellow Pages/N IS or BIND/ 
H esoid. 


FILES 


/etc/protocols The protocols definition file. 


SEE ALSO 
getprotoent(3), Guideto Ydlow Pages Service, Guide to BIN D/H edod Service 
Linux, 18 October 1995 


rcsfile 


restile— Format of RCS file 


DESCRIPTION 
An RCS file's contents are described by the grammar bdow. 


The text is free format: space, backspace tab, newline, vertical tab, form feed, and carriage return (collectivay, whitespace) 
have no significance except in strings. H owever, whitespace cannot appear within an!ID, num, or sym, and an RCS file must 
end with a newline. 


Strings are enclosed by e. If a string contains ae, it must be doubled; otherwise, strings can contain arbitrary binary data. 


The meta syntax uses the following conventions: ! (bar) separates alternatives; ¢ and } enclose optional phrases. { and }* 
enclose phrases that can be repeated zero or more times. 4 and {+ enclose phrases that must appear at least once and can be 
repeated. Terminal symbols are in boldface; non-terminal symbols are in italics 


restext ::= admin {delta}* desc {deltatext }* 
admin ::= head {num}; 
{ branch {num}; } 
access {id}*; 
symbols {sym : num}*; 
locks {id : num}*; {strict 3} 


{ comment {string}; } 
{ expand {string}; } 
{ newphrase }* 
delta ::= num 
date num; 
author id; 
state {id}; 
branches {num}*; 
next {num}; 
{ new-phrase }* 
desc ::= desc string 
deltatext ::= num 
log string 
{ newphrase }* 
text string 
num ::= {digit | .}+ 
BOGE See ee PP hl ae St Bog 
id ::= {num} idchar {idchar | num}* 
sym ::= {digit }* idchar {idchar | digit }* 
idchar ::= any visible graphic character except special 
special r= $$, |. ts t; 1 @ 
string ::= @{any character, with @doubled}*@ 
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newphrase ::= id word* ; 

word ::=id | num | string | : 
Identifiers are case sensitive K eywords are in lowercase only. T he sets of keywords and identifiers can overlap. In most 
environments, RCS uses the! SO 8859/1 encoding: visible graphic characters are codes 041-176 and 240-377, and 
whitespace characters are codes 010-015 and 040. 


D ates, which appear after the date keyword, are of the form Y.mm.dd.hh.mm.ss, whereY is the year, mm the month (01-12), 
dd the day (01-31), hh the hour (00-23), mm the minute (00-59), and ssthe second (00-60). Y contains just the last two 
digits of the year for years from 1900 through 1999, and all the digits of years thereafter. D ates use the Gregorian calendar; 
times use UTC. 


The newphrase productions in the grammar are reserved for future extensions to the format of RCS files. N 0 newphrase will 
begin with any keyword already in use 


The delta nodes form atree. All nodes whose numbers consist of a single pair (such as 2.3, 2.1, 1.3, and so on) areon the 
trunk and are linked through the next field in order of decreasing numbers. The head fidd in the admin node points to the 
head of that sequence (contains the highest pair). The branch node in the admin node indicates the default branch (or 
revision) for most RCS operations. If empty, the default branch is the highest branch on the trunk. 


All delta nodes whose numbers consist of 2n fidds (n2) (such as 3.1.1.1, 2.1.2.2, and so on) are linked as follows. All nodes 
whose first 2n-1 number fields are identical are linked through the next field in order of increasing numbers. For each such 
sequence, the delta node whose number is identical to the first 2n-2 number fields of the deltas on that sequence is called 
the branchpoint. The branches field of anode contains alist of the numbers of the first nodes of all sequences for which it is 
a branchpoint. T hislist is ordered in increasing numbers. 


The following diagram shows an example of an RCS file's organization. 
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resolver 
IDENTIFICATION 


Author: Walter F. Tichy, Purdue University, W est Lafayette, IN , 47907. M anual Page Revision: 5.6; Release D ate: 1995/ 
06/05. Copyright 1982, 1988, 1989, Walter F. Tichy. Copyright 1990, 1991, 1992, 1993, 1994, 1995, Paul Eggert. 


SEE ALSO 


resintro(1), ci(1), co(1), ident(1), res(1), resclean(1), resdiff(1), resmerge(1), rlog(1), Walter F. Tichy, RCS, “A System 
for Version Control,” Software— Practice & Experience, 15, 7 (July 1985), 637-654. 


GNU, 5 June1995 


resolver 


resolver— Resolver configuration file. 


SYNOPSIS 


/etc/resolv.conf 


DESCRIPTION 


The resolver is a set of routines in theC library (reso1v(3)) that provides access to the Internet D omain N ameSysten. The 
resolver configuration file contains information that is read by the resolver routines the first time they are invoked by a 
process. The file is designed to be human readable and contains a list of keywords with values that provide various types of 
resolver information. 


On anormally configured system, this file should not be necessary. The only nameserver to be queried will be on the local 
machine, the domain name is determined from the host name and the domain search path is constructed from the domain 
name 


Thedifferent configuration options are 


nameserver Internet address (in dot notation) of anameserver that the resolver should query. Up to 
MAXNS (Currently 3) nameservers may be listed, one per keyword. If there are multiple servers, 
the resolver library queries them in the order listed. If no nameserver entries are present, the 
default is to use the nameserver on the local machine (The algorithm used is to try a 
nameserver, and if the query times out, try the next until you run out of nameservers, and 
then repeat trying all the nameservers until a maximum number of retries are made) 

domain Local domain name M ost queries for names within this domain can use short names 
relative to the local domain. If no domain entry is present, the domain is determined from 
the local hostname returned by gethostname(2); the domain part is taken to be everything 
after the first .. Finally, if the hostname does not contain a domain part, the root domain is 
assumed. 

search Search list for hostname lookup. T he search list is normally determined from the local 
domain name; by default, it contains only the local domain name. T his may be changed by 
listing the desired domain search path following the search keyword with spaces or tabs 
separating the names. M ost resolver queries will be attempted using each component of the 
search path in turn until a match is found. N ote that this process may be slow and will 
generate a lot of network traffic if the servers for the listed domains are not local and that 
queries will time out if no server is available for one of the domains. 
The search list is currently limited to six domains with a total of 256 characters. 

sortlist sortlist allows addresses returned by gethostbyname to be sorted. A sort list is specified by 
IP address netmask pairs. The netmask is optional and defaults to the natural netmask of 
the net. TheIP address and optional network pairs are separated by slashes. U p to 10 pairs 
may be specified. 
sortlist 130.155.160.0/255.255.240.0 130.155.0.0 
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options options allows certain internal resolver variables to be modified. T he syntax is 
options option ... 
where opti on is one of the following: 
debug S&S RESDEBUG IN res.options. 


ndots:n sets a threshold for the number of dots that must appear in aname given to 
res_query (S€@ resolver(3)) before an initial absolute query will be made. The default forn is 
1, meaning that if there are any dotsin aname, thename will be tried first as an absolute 
name before any search list elements are appended to it. 


The domain and search keywords are mutually exclusive. If more than one instance of these keywords is present, the last 
instance wins. 


The search keyword of a system's resolv.conf file can be overridden on a per-process basis by setting the environment 
variable LOcALDOMAIN to a space-separated list of search domains. 


The options keyword of asystem’s resolv. conf file can be amended on a per-process basis by setting the environment 
variable RES_opT1ons to a Space-separated list of resolver options as explained previously. 


The keyword and value must appear on a single line, and the keyword (such aS nameserver) must start the line The value 
follows the keyword, separated by whitespace. 


FILES 


/etc/resolv.conf 
SEE ALSO 


gethostbyname(3), resolver(3), hostname(7), named(8), Name Server O perations Guide for BIN D 
11 N ovenber 1993 
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securetty— File that lists ttys from which root can log in. 


DESCRIPTION 


/etc/securetty IS used by login(1); the file contains the device names of tty lines (one per line, without leading /dev/) on 
which root is allowed to log in. 


FILES 


/etc/securetty 
SEE ALSO 
login(1) 
Linux, 29 D cenber 1992 


Services 


services— Internet network services list. 


DESCRIPTION 


services iSa plain ASCII file providing a mapping betwee friendly textual names for Internet services and thar underlying 
assigned port numbers and protocol types. Every networking program should look into this file to get the port number (and 


Servi CeS 


protocol) for its service. TheC library routines getservent(3), getservbyname(3), getservbyport(3), setservent(3), and 
endservent(3) Support querying this file from programs. 


Port numbers are assigned by the IAN A (Internet Assigned N umbers Authority), and their current policy is to assign both 
TCP and UDP protocols when assigning a port number. Therefore, most entries will have two entries, even for TC P-only 
services. 

Port numbers beow 1024 (so-called low-numbered ports) can only bebound to by root (see bina(2), tcp(7), and udp(7).) 
This is so that clients connecting to low-numbered ports can trust that the service running on the port isthe standard 
implementation and not a rogue service run by a user of the machine W dl-known port numbers specified by the IANA are 
normally located in this root-only space. 

The presence of an entry for a service in the services file does not necessarily mean that the service is currently running on 
the machine. See inetd. conf(5) for the configuration of Internet services offered. N ote that not all networking services are 
started by ineta(8) and so won't appear in inetd. conf(5). In particular, news(N NTP) and mail (SM TP) servers are often 
initialized from the system boot scripts. 

The location of the services file is defined by PATH SERVICES in /usr/include/netdb.h. T his is usually set to /etc/services. 
Each line describes one service and is of the form: 


service-name port /protocol [aliases ...] 


service-name The friendly name the service is known by and looked up und@. It is case sensitive. O ften, 
the client program is named after theservice-name. 

port The port number (in decimal) to use for this service 

protocol The type of protocol to be used. This fidd should match an entry in the protoco1s(5) file 
Typical values include tcp and udp. 

aliases An optional space or tab-separated list of other names for this service (see the Bugs section 


bedow). Again, the names are case sensitive. 
Either spaces or tabs may be used to separate the fields. 
Comments are started by the hash sign (#) and continue until the end of the line Blank lines are skipped. 


Theservice-name Should begin in thefirst column of the file because leading spaces are not stripped. service-nameScan be 
any printable characters excluding space and tab; however, a conservative choice of characters should be used to minimize 
inter-operability problems. For example, a-z, 0-9, and hyphen (-) would seem a sensible choice 


Lines not matching this format should not be present in the file (Currently, they are silently skipped by getservent(3), 
getservbyname(3), and getservbyport(3). H owever, this behavior should not be relied on.) 


Asa backwards compatibility feature, the slash (/) between the port number and protocol name can in fact be either a slash 
or acomma(,). Use of thecommain modern installations is depreciated. 


This file might be distributed over a network using a network-wide naming service such as Yellow Pages/N IS or BIND/ 
H esiod. 


A sample services file might look like this: 


netstat 15/tcp 

qotd 17/tcp quote 

msp 18/tcp # message send protocol 
msp 18/udp # message send protocol 
chargen 19/tcp ttytst source 

chargen 19/udp ttytst source 

ftp 21/tcp 

# 22 - unassigned 


telnet 23/tcp 
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BUGS 
There isa maximum of 35 aliases, due to the way the getservent(3) code is written. 


Lines longer than Bursiz (currently 1024) characters will be ignored by getservent(3), getservbyname(3), and 
getservbyport(3). H owever, this will also cause the next line to be misparsed. 


FILES 
/etc/services The Internet network services list 
/usr/include/netdb.h Definition of _PATH_SERVICES 

SEE ALSO 


getservent(3), getservbyname(3), getservbyport(3), setservent(3), endservent(3), protocols(5), listen(2), inetd. conf(5), 
inetd(8), Assigned Numbers RFC, most recently RFC 1700 (AKA STD 0002), Guide to Yellow Pages Service, Guide to 
BIN D/H esiod Service 


Linux, 11 January 1996 
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shells— Pathnames of valid login shells. 


DESCRIPTION 


/etc/shells isa text file that contains the full pathnames of valid login shals. This file is consulted by chsh(1) and is available 
to be queried by other programs. 


EXAMPLES 
/etc/shells may contain the following paths: 
/bin/sh 
/bin/csh 


FILES 


/etc/shells 


SEE ALSO 
chsh(1) 
21 November 1993 
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syslog.conf— syslogd(8) configuration file. 


DESCRIPTION 


The syslog.cont fileis the configuration file for the sys1ogd(8) program. It consists of lines with two fields: the selector 
fidd, which specifies the types of messages and priorities to which the line applies, and an action fidd, which specifies the 
action to be taken if a message syslogd received matches the selection criteria. There cannot be any spacesin the action field. 
The selector field is separated from the action fidd by one or more tab or space characters. (T his isa departure from the 
standard BSD way of doing things; both tabs and spaces can be used to separate the selector from the action.) 


The selector functions are encoded as a facility, a period (.), and alevd, with no intervening whitespace. Both the facility 
and the level are case insensitive. 


sydog.conf 


The facility describes the part of the system generating the message and is one of the following keywords: auth, authpriv, 
cron, daemon, kern, lpr, mail, mark, news, syslog, user, uucp, aNd localo through local7. T hese keywords (with the exception 
of mark) correspond to the similar pv Loc_ values specified to the openiog(3) and sysiog(3) library routines. 


The level describes the severity of the message and is a keyword, optionally preceded by an equals (=), from the following 
ordered list (higher to lower): emerg, alert, crit, err, warning, notice, info, and debug. 1 hese keywords correspond to the 
similar Dv Log_ values specified to the sysiog library routine. 


Se syslog(3) for further descriptions of both the facility and level keywords and their significance. 


If a recaved message matches the specified facility and is of the specified level (or ahigher level if level was specified without 
=), the action specified in the action fidd will be taken. 


M ultiple sd ectors may be specified for a single action by separating then with semicolon (;) characters. It isimportant to 
note, howeve,, that each selector can modify the ones preceding it. 


M ultiple facilities may be specified for a single leva by separating then with comma (,) characters. 
An asterisk (*) can be used to specify all facilities or all levds. 


The special facility “mark” receives a message at priority “info” every 20 minutes (see syslogd(8)). Thisis not enabled by a 
facility fidd containing an asterisk. 


The special level “none” disables a particular facility. 

The action field of each line specifies the action to be taken when the selector field selects a message. T here are four forms: 
A pathname (beginning with a leading slash). Selected messages are appended to the file 

A hostname (preceded by an at (@) sign). Selected messages are forwarded to the syslogd program on thenamed host. 

A comma-separated list of users. Selected messages are written to those users if they are logged in. 

An asterisk. Sdected messages are written to all logged-in users. 

Blank lines and lines whose first non-blank character is a hash (#) character are ignored. 


EXAMPLES 
A configuration file might appear as follows: 


# Log all kernel messages, authentication messages of 

level notice or higher and anything of level err or 

higher to the console. 

Don't log private authentication messages! 

-err;kern.*; auth. notice; authpriv.none /dev/console 


+ Fb He TE 


Fe 


Log anything (except mail) of level info or higher 
Don't log private authentication messages! 
.info;mail.none;authpriv.none /var/log/messages 


Fe 


* 


Fe 


Log debug messages only 
-=debug /var/log/debug 


* 


# The authpriv file has restricted access. 
authpriv.* /var/log/secure 


# Log all the mail messages in one place. 
mail.* /var/log/maillog 


# Everybody gets emergency messages, plus log them on another 

# machine. 

*,emerg * 

* emerg @arpa.berkeley.edu 
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# Root and Eric get alert and higher messages. 
* alert root, eric 


# Save mail and news errors of level err and higher in a 
# special file. 


uucp,news.crit /var/log/spoolerr 
FILES 

/etc/syslog.conf The syslogd(8) configuration file 
BUGS 


T he effects of multiple selectors are sometimes not intuitive For example mail.crit,*.err will select mail facility messages at 
the leva of err or higher, not at the leva of crit or higher. 


SEE ALSO 
syslog(3), syslogd(8) 
10 May1991 
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termcap— T erminal capability database 


DESCRIPTION 


The termcap database is an obsolete facility for describing the capabilities of character-cell terminals and printers. It is 
retained only for capability with old programs; new ones should use the terminfo(5) database and associated libraries. 


/etc/termcap isan ASCII file (the database master) that lists the capabilities of many different types of terminals. Programs 
can read termcap to find the particular escape codes needed to control the visual attributes of the terminal actually in use. 
(O ther aspects of the terminal are handled by stty.) The termcap database is indexed on the Term environment variable. 


termcap entries must be defined on a single logical line, with \ used to suppress the newline Fidds are separated by :. The 
first field of each entry starts at the left-hand margin and contains a list of names for the terminal, separated by !. 





The first subfidd may (in BSD termcap entries from versions 4.3 and prior) contain a short name consisting of two 
characters. T his short name may consist of capital or small letters. In 4.4 BSD termcap entries, this field is omitted. 


The second subfidd (first in the newer 4.4 BSD format) contains the name used by the environment variable Term. It should 
be spdled in lowercase letters. Se ectable hardware capabilities should be marked by appending ahyphen and a suffix to this 
name. U sual suffixes are w (more than 80 characters wide), am (automatic margins), nam (no automatic margins) and rv 
(reverse video display). The third subfidd contains along and descriptive name for thistermcap entry. 


Subsequent fidds contain the terminal capabilities; any continued capability lines must be indented one tab from the left 
margin. 


Although there is no defined order, it is suggested to write first Boolean, then numeric, and at last string capabilities, each 
sorted alphabetically without looking at lower or upper spelling. C apabilities of similar functions can be written in oneline 


Example: 


Head line: vtjvt101|DEC VT 101 terminal in 80 character mode: \ 

Head line: Vt{vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\ 
Boolean: :bs:\ 

Numeric: :co#80:\ 

String: :sr=nE[H:\ 


termcap 


Boolean Capabilities 





5i Printer will not echo on screen 

am Automatic margins which means automatic line wrap 

bs Ctrl+H (8 dec.) performsa backspace 

bw Backspace on left margin wraps to previous line and right margin 
da Display retained above screen 

db Display retained below screen 

e0 A space erases all characters at cursor position 

es Escape sequences and special characters work in status line 
gn Generic device 

he This is ahardcopy terminal 

HC The cursor is hard to see when not on bottom line 

hs Has astatus line 

hz H azeltine bug; the terminal cannot print tilde characters 
in Terminal inserts nulls, not spaces, to fill whitespace 

km Terminal has a meta key 

mi Cursor movenent works in insert mode 

ms Cursor movenent works in standout/underline mode 

NP No pad character 

NR ti does not reverse te 

nx No padding; must use XO N/XO FF 

os Terminal can overstrike 

ul Terminal undellines, although it cannot overstrike 

xb Beehive glitch; Fl sends Escape and F2 sends °C 

xn N ewline/wraparound glitch 

xO Terminal uses XON/XOFF protocol 

xs Text typed over standout text will be displayed in standout 
xt T eleray glitch; destructive tabs and odd standout mode 





Numeric Capabilities 








co Number of columns 

dB D elay in milliseconds for backspace on hardcopy terminals 

dc D elay in milliseconds for carriage return on hardcopy terminals 
dF D elay in milliseconds for form feed on hardcopy terminals 

dN D elay in milliseconds for newline on hardcopy terminals 

dT D elay in milliseconds for tabulator stop on hardcopy terminals 
dV D elay in milliseconds for vertical tabulator stop on hardcopy terminals 
it Difference between tab positions 

lh H eight of soft labeas 

Lm Lines of memory 

lw W idth of soft labels 


continues 
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Numeric Capabilities 





li 
N1 
pb 
sg 
ug 
vt 


ws 


N umber of lines 

N umber of soft label's 

Lowest baud rate that needs padding 

Standout glitch 

Underline glitch 

Virtual terminal number 

Width of status line if different from screen width 





String C apabilities 





1 
!2 
13 
#1 
#2 


Shifted save key 
Shifted suspend key 
Shifted undo key 
Shifted help key 
Shifted home key 
Shifted input key 
Shifted cursor left key 
Redo key 

Help key 

M ark key 

M essage key 

M ove key 

N ext-object key 
Open key 

Options key 
Previous-object key 
Print key 

Shifted message key 
Shifted move key 
Shifted next key 
Shifted options key 
Shifted previous key 
Shifted print key 
Shifted redo key 
Shifted replace key 
Shifted cursor right key 
Shifted resume key 
Shifted cancd key 
Reference key 
Refresh key 
Replace key 

Restart key 








String C apabilities 


termcap 





&5 
&6 
&7 
&8 
&9 
*0 
bal 
*2 
*3 
*4 
*5 
*6 
Ld 
*8 
*9 
@Q 
@ 
@2 
@3 
@4 
@5 
@6 
@7 
@8 
@9 
al 
AL 
ac 
ae 
as 
be 
bl 
bt 
cb 
cc 
cd 
ce 
ch 
cl 
cm 


CM 


Resume key 

Save key 

Suspend key 

Undo key 

Shifted begin key 

Shifted find key 

Shifted command key 

Shifted copy key 

Shifted create key 

Shifted delete character 

Shifted delete line 

Sdect key 

Shifted end key 

Shifted clear line key 

Shifted exit key 

Find key 

Begin key 

Cancel key 

Close key 

Command key 

Copy key 

Create key 

End key 

Enter/send key 

Exit key 

Insert one line 

Insert 1 lines 

Pairs of block graphic characters to map alternate character set 
End alternative character set 

Start alternative character set for block graphic characters 
Backspace if not “H 

Audio bell 

M ove to previous tab stop 

Clear from beginning of lineto cursor 
Dummy command character 

Clear to end of screen 

Clear to end of line 

M ove cursor horizontally only to column %1 
Clear screen and cursor home 

Cursor move to row %1 and column %2 (on screen) 
M ove cursor to row %1 and column %2 (in memory) 





continues 


Part V: FileFormats 


String C apabilities 





er 
cs 
ct 
cv 
de 
DC 
dl 
DL 
dm 
do 
DO 
ds 
eA 
ec 
ed 
ei 
Tf 
fs 
FA 
F2 
F3 


FQ 
FA 
FB 


FZ 
Fa 
Fb 


EP 
hd 
ho 
hu 
if 
i3 
is 
ic 
Ic 
if 


im 


Carriage return 

Scroll region from line %1 to %2 
Clear tabs 

M ove cursor vertically only to line %1 
D elete one character 

D elete %1 characters 

D elete one line 

D elete x1 lines 

Begin delete mode 

Cursor down one line 

Cursor down #1 lines 

Disable status line 

Enable alternate character set 

Erase %1 characters starting at cursor 
End delete mode 

End insert mode 

Formfeed character on hardcopy terminals 
Return character to its position before going to status line 
Thestring sent by function key f11 
The string sent by function key f12 
Thestring sent by function key f13 


The string sent by function key f19 
Thestring sent by function key f20 
Thestring sent by function key f21 


Thestring sent by function key f45 
The string sent by function key f46 
Thestring sent by function key f47 








The string sent by function key f63 
M ove cursor a half line down 
Cursor home 

M ove cursor a half line up 
Initialization string 1 at login 
Initialization string 3 at login 
Initialization string 2 at login 
Insert one character 

Insert %1 characters 
Initialization file 

Begin inset mode 
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String C apabilities 








ip Insert pad time and needed special characters after insert 
ip Initialization program 

Kt U pper-left key on keypad 

K2 Center key on keypad 

K3 U pper-right key on keypad 

K4 Bottom-left key on keypad 

K5 Bottom-right key on keypad 
ko Function key 0 

k1 Function key 1 

k2 Function key 2 

k3 Function key 3 

k4 Function key 4 

k5 Function key 5 

k6 Function key 6 

k7 Function key 7 

k8 Function key 8 

kg Function key 9 

k; Function key 10 

ka Clear all tabs key 

kA Insert line key 

kb Backspace key 

kB Back tab stop 

kC Clear screen key 

kd Cursor down key 

kD Key for delete character under cursor 
ke Turn keypad off 

kE K ey for clear to end of line 

kF K ey for scrolling forward/down 
kh Cursor home key 

kH Cursor down key 

kI Insert character/insert mode key 
kl Cursor left key 

kL Key for delete line 

kM Key for exit insert mode 

kN Key for next page 

kP K ey for previous page 

kr Cursor right key 

kR Key for scrolling backward/up 
ks Turn keypad on 

kS Clear to end of screen key 

kt Clear this tab key 


continues 
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String C apabilities 





kT 
ku 
i) 
1 





LE 
LF 
LO 
mb 
MC 
md 
me 
mh 
mk 
ML 
mm 
mo 
mp 
mr 
MR 
nd 
nw 
pe 
pf 
pk 
pl 
pn 
po 
po 
ps 
px 
rq 
r2 
r3 
RA 
rec 


rf 


Sé& tab here key 

Cursor up key 

Label of zeroth function key, if not f0 
Label of first function key, if not f1 
Label of first function key, if not f2 


Label of tenth function key, if not f10 
Cursor left one character 

M ove cursor to lowe-left corner 

Cursor left %1 characters 

Turn soft labels off 

Turn soft labels on 

Start blinking 

Clear soft margins 

Start bold mode 

End all modes such aS so, us, mb, md, and mr 
Start half bright mode 

D ark mode (Characters invisible) 

Se left soft margin 

Put terminal in meta mode 

Put terminal out of meta mode 

Turn on protected attribute 

Start reverse mode 

Se right soft margin 

Cursor right one character 

Carriage return command 

Padding character 

Turn printer off 

Program key %1 to send string %2 asif typed by user 
Program key %1 to execute string %2 in local mode 
Program soft label %1 to show string %2 
Turn the printer on 

Turn the printer on for %1 (<256) bytes 
Print screen contents on printer 

Program key %1 to send string %2 to computer 
Reset string 1 to set taeminal to sane modes 
Reset string 2 to set taeminal to sane modes 
Reset string 3 to set taminal to sane modes 
Disable automatic margins 

Restore saved cursor position 

Reset string filename 
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String C apabilities 





RF Request for input from terminal 

RI Cursor right %1 characters 

rp Repeat character %1 for %2 times 

rP Padding after character sent in replace mode 

rs Reset string 

RX Turn off XON/XOFF flow control 

sa Set %1 %2 %3 %4 %5 %6%7 %8 %9 attributes 

SA Enable automatic margins 

sc Save cursor position 

se End standout mode 

sf Normal scroll oneline 

SF Normal scroll %1 lines 

$0 Start standout mode 

sr Reverse scroll 

SR Scroll back %1 lines 

st Se tabulator stop in all rows at current column 
SX Turn on XON/XOFF flow control 

ta M ove to next hardware tab 

tc Read in terminal description from another entry 
te End program that uses cursor motion 

ti Begin program that uses cursor motion 

ts M ove cursor to column %1 of status line 

uc Underline character under cursor and move cursor right 
ue End undelining 

up Cursor up oneline 

UP Cursor up %1 lines 

us Start underlining 

vb Visible bell 

ve Normal cursor visible 

vi Cursor invisible 

vs Standout cursor 

wi Sé window from line %1 to %2 and column %3 to %4 
XF XOFF character if not “S 





Thee are several ways of defining the control codes for string capabilities: 
Normal characters except *, \, and % represent thenselves. 
A “x means Ctrl+x. Ctrl+A equals 1 decimal. \x meansa special code. x can be oneof the following characters: 


E Escape (27). 
n Linefeed (10). 
r Carriage return (13). 


t Tabulation (9). 
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(on 


3 


+ 


co Q 


Backspace (8). 

Form feed (12). 

Null character. A \xxx specifies the octal character xxx. 

Increments parameters by one 

Single parameter capability. 

Add value of next character to this parameter and do binary output. 
Do ASCII output of this parameter with a fidd width of 2. 

Do ASCII output of this parameter with a fidd width of 3. 

Print a% 


If you use binary output, then you should avoid the null character because it terminates the string. You should reset tabulator 
expansion if a tabulator can be the binary output of a parameter. 


W arning: T he preceding metacharacters for parameters may bewrong; they document M inix termcap, which may not be 


compatible with Linux termcap. 


The block graphic characters can be specified by three string capabilities: 


as 
ae 


ac 


The following names are available: 
" 


) 


> Q > D> - 


PFU. 


Start the alternative charset. 
End it. 


Pairs of characters. The first character is the name of the block graphic symbol and 
the second character is its definition. 


— 


Right arrow (>) 
Left arrow (< 
Down arrow 
Full square (# 
Latern (#) 

U pper arrow (*) 

Rhombus (+) 

Chess board (:) 

D egree (') 

Plus-minus (#) 

Square (#) 

Right bottom corner (+) 
Right upper corner (+) 
Left upper corner (+) 

Left bottom corner (+) 
Cross (+) 

U pper horizontal line (-) 
M iddle horizontal line (-) 
Bottom horizontal line (_) 
Left tee (+) 

Right tee (+) 

Bottom tee (+) 

N ormal tee (+) 

Vertical line (_) 
Paragraph (227) 


—_~~— 


v) 


= 


tzfile 1197 


The values in parentheses are suggested defaults that are used by curses if the capabilities are missing. 
SEE ALSO 
termcap(3), curses(3), terminto(5) 


Linux 


ttytype 
ttytype— T minal name and device list. 


DESCRIPTION 


The /etc/ttytype file associates termcap/terminfo taminal type names with tty lines. Each line consists of aterminal type, 
followed by whitespace, followed by atty name (a device name without the /dev/ prefix). 


This association is used by the program tset(1) to set the nvironment variable Term to the default terminal name for the 
user’s current tty. 


This facility was designed for a traditional time-sharing environment featuring character-cell terminals hardwired to aUNIX 
minicomputer. It is little used on modern workstation and personal UN IXes. 


EXAMPLE 
A typical /etc/ttytype is 


con80x25 tty1 
vt320 ttysd 


FILES 


/etc/ttytype The tty definitions file 


SEE ALSO 


getty(1), terminfo(5), termcap(5) 
Linux, 24 July 1993 


tzfile 


tzfile— Timezone information. 


SYNOPSIS 


#include <tzfile.h> 


DESCRIPTION 


The time zone information files used by tzset(3) begin with bytes reserved for future use, followed by six four-byte values of 
type long, written in a “standard” byte order (the high-order byte of the value is written first). T hese values are, in order 


tzh_ttisgmtent Thenumber of GM T/local indicators stored in the file. 

tzh_ttisstdent Thenumber of standard/wall indicators stored in the file. 

tzh_leapcnt Thenumber of leap seconds for which data is stored in the file. 

tzh_timecnt The number of “transition times” for which data is stored in the file. 

tzh_typecnt Thenumber of “local time types” for which data is stored in the file (must not be zero). 


tzh_charcnt Thenumber of characters of “time zone abbreviation strings” stored in the file 
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The preceding header is followed by tzh_timecnt four-byte values of type long, sorted in ascending order. T hese values are 
written in “standard” byte order. Each is used as a transition time (as returned by time(2)) at which the rules for computing 
local time change. N ext come tzh_timecnt one byte values of type unsigned char; each one tells which of the different types 
of “local time” types described in the file is associated with the same-indexed transition time T hese values serve as indices 
into an array of ttinfo structures that appears next in the file; these structures are defined as follows: 

struct ttinfo { 

long tt_gmtoff; 

int tt_isdst; 

unsigned int tt_abbrind; 

}; 


Each structure is written as a four-byte value for tt_gmtoff of type long, in a standard byte order, followed by a one byte 
value for tt_isdst and a one-byte value for tt_abbrind. In each structure, tt_gmtoff gives the number of seconds to be added 
to GMT, tt_isdst tells whether tm_isdst should be set by localtime(3) and tt_abbrind serves as an index into the array of 
time zone abbreviation characters that follow the ttinfo structures in the file 


Then there are tzh_leapent pairs of four-byte values, written in standard byte orde;; the first value of each pair gives thetime 
(as returned by time(2)) at which a leap second occurs; the second gives the total number of leap seconds to be applied after 
the given time. The pairs of values are sorted in ascending order by time 


Then there are tzh_ttisstdcent standard/wall indicators, each stored as a one-byte value; they tal whether thetransition times 
associated with local time types were specified as standard time or wall clock time and are used when atime zone file is used 
in handling PO SIX-style time zone environment variables. 


Finally, there are tzh_ttisgmtcnt GM T /local indicators, each stored as a one byte value; they tdl whether thetransition times 
associated with local time types were specified as GM T or local timeand are used when a time zone file is used in handling 
POSIX-style time zone environment variables. 





Localtime uses the first standard-time ttinfo structure in the file (or simply the first ttinfo structure in the absence of a 
standard-time structure) if either tzh_timecnt is zero or the time argument is less than the first transition time recorded in the 
file 


SEE ALSO 


newctime(3) 


utmp, wtmp 


utmp, wtmp— Login records. 


SYNOPSIS 


#include <utmp.h> 


DESCRIPTION 


The utmp file allows you to discover information about who is currently using the system. T here may be more users currently 
using the system because not all programs use utmp logging. 


Warning: utmp must not be writable because many system programs depend on its integrity. You risk faked systen log files 
and modifications of system files if you leave utmp writable to any user. 


The file is a sequence of entries with the following structure declared in the include file 


#define UT_UNKNOWN Q 
#define RUN LVL 1 
#define BOOT_TIME 2 
#define NEW_TIME 3 
#define OLD TIME 4 


utmp, wtmp 


#define INIT_PROCESS 5 
#define LOGIN PROCESS 6 
#define USER_PROCESS 7 
#define DEAD PROCESS 8 


#define UT_LINESIZE 12 
#define UT_NAMESIZE 8 
#define UT_HOSTSIZE 16 


struct utmp { 


short ut_type; /* type of login */ 

pid_t ut_pid; /* pid of process */ 

char ut_line[UT_LINESIZE];  /* device name of tty - "/dev/" */ 
char ut_id[2]; /* init id or abbrev. ttyname */ 
time_t ut_time; /* login time */ 

char ut_user[UT_NAMESIZE]; /* user name */ 

char ut_host[UT_HOSTSIZE]; /* host name for remote login */ 
long ut_addr; /* IP addr of remote host */ 


}; 


This structure gives the name of the special file associated with the user's terminal, the user’s login name, and the time of 
login in the form of time(2). String fields are terminated by \o if they are shorter than the size of the field. 


The first entries ever created result from init(8) processing inittab(5). Before an entry is processed, though, init(8) cleans 
Up utmp by setting ut_type to DEAD_PROcESS, Clearing ut_user, ut_host and ut_time with null bytes for each record that ut_type 
iS Not DEAD_PROCESS Or RUN_LVL and whereno process with PID ut_pid exists. If no anpty record with the needed ut_id can be 
found, init creates a new one. It sets ut_id from the inittab, ut_pid and ut_time to the current values, and ut_type to 
INIT_PROCESS. 


getty(8) locates the entry by the PID , changes ut_type to LogIN_PROcESS, changes ut_time, sets ut_line and waits for 
connection to be established. 1ogin(8), after a user has been authenticated, changes ut_type to USER_PROCESS, Changes ut_time, 
and sets ut_host and ut_addr. D eoending on getty(8) and login(8), records may be located by ut_line instead of the 
preferable ut_pid. 


When init(8) finds that a process has exited, it locates its utmp entry by ut_pid, sets ut_type to DEAD PROCESS, and clears 
ut_user, ut_host, and ut_time with null bytes. 


xterm(1) and other terminal emulators directly create a useR_PRocess record and generate the ut_id by using the last two 
letters of /dev/ttyp%c or by using p%d for /dev/pts/%d. 


If they find a peap_process for this ID, they recycleit; otherwise they create anew entry. If they can, they will mark it as 
DEAD_PROCESS On exiting and it is advised that they null ut_line, ut_time, ut_user, and ut_host as wall. 


xdm(8) should not create an utmp record because there is no assigned terminal. Letting it create onewill result in trouble such 
aS finger: cannot stat /dev/machine.dom. It should create wtmp entries, though, just like ftpa(8) does. 


telnetd(8) S&Sup a LOGIN_PRocEss entry and leaves the rest to 1ogin(8) as usual. After the T elnet session ends, te1netd(8) 
cleans up utmp in the described way. 


The wtmp file records all logins and logouts. Its format is exactly like utmp except that a null username indicates a logout on 
the associated terminal. Furthermore, the teminal name ~ with username shutdown Or reboot indicates a system shutdown or 
reboot and the pair of terminal names "!"/"}" logs the old/new system time when date(1) changesit. wtmp is maintained by 
login(1) and init(1) and some variation of getty(1). N either of these programs creates the file, so if it is removed, record- 
keeping is turned off. 


FILES 


/var/run/utmp 
/var/log/wtmp 
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CONFORMING TO 


Linux utmp entries conform neither to v7/BSD nor to SYSV: They are a mix of the two. v7/BSD has fewer fidds; most 
importantly, it lacks ut_type, which causes native v7/BSD -like programs to display (for example) dead or login entries. 
Further there is no configuration file that allocates slots to sessions. BSD does so because it lacks ut_ia fields. In Linux (asin 
SYSV), the ut_id fidd of a record will never change once it is set, which reserves that slot without needing a configuration 
file. Clearing ut_id may result in race conditions leading to corrupted utmp entries and potential security holes. Clearing the 
previously mentioned fields by filling them with null bytes is not required by SYSV semantics, but it allows you to run many 
programs that assume BSD semantics and that do not modify utmp. Linux uses the BSD conventions for line contents. SYSV 
only uses the type field to mark them and logs informative messages such as new time in theline fidd. SYSV has onemore 
fidd to log the exit status of dead processes. UT_UNKNowN Seams to be a Linux invention. Thereis no type accounTiNe in Linux. 
SYSV has no ut_host Or ut_addr fidds. Unlike various other systems, where utmp logging can be disabled by removing the 
file, utmp must always exist on Linux. If you want to disable who(1), then do not make utmp world readable. 


RESTRICTIONS 
The file format is machine dependent, so it is recommended that it be processed only on the machine architecture where it 
got created. 
SEE ALSO 
ac(1), date(1), last(1), login(1), who(1), getutent(3), init(8) 
20 July 1996 
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uuencode— Format of an encoded uuencodefile. 


DESCRIPTION 
Files output by uuencode(1) consist of aheader line, followed by anumber of body lines, and a trailer line The uudecode(1) 
command will ignore any lines preceding the header or following the trailer. Lines preceding a header must not, of course, 
look like a header. 
The header line is distinguished by having the first sx characters begin. The word begin iSfollowed by amode (in octal) and 
a string that names the remote file A space separates the three items in the header line 
The body consists of anumber of lines, each at most 62 characters long (including the trailing newline). T hese consist of a 
character count, followed by encoded characters, followed by anewline The character count is a single printing character 
and represents an integer, the number of bytes the rest of the line represents. Such integers are always in the range from 0 to 
63 and can be determined by subtracting the character space (octal 40) from the character. 
Groups of three bytes are stored in four characters, six bits per character. All are offset by a space to make the characters 
print. T he last line may be shorter than the normal 45 bytes. If the szeis not a multiple of three, this fact can be determined 
by the value of the count on the last line. Extra garbage will be included to make the character count a multiple of four. The 
body is terminated by a line with acount of zero. This line consists of one ASCII space 


Thetrailer line consists of end on aline by itsef. 


SEE ALSO 


uuencode(1), uudecode(1), uusend(1), uucp(1), mai1(1) 


HISTORY 
The uuencode file format appeared in BSD 4.0. 
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xF86Config— Configuration file for X Free86. 


DESCRIPTION 


X Free86 uses a configuration file called xFsécontig for its initial setup. T his configuration file is searched for in the following 
places: 


/etc/XF86Config 
<XRoot >/1lib/X11/XF86Config.hostname 
<XRoot >/1lib/X11/XF86Config 


<kRoot > refers to the root of the X11 install tree 
This file is composed of anumber of sections Each section has the form: 


Section "SectionName" 
SectionEntry ... 
EndSection 


The section names are 


Files File pathnames 
ServerFlags Server flags 

Keyboard Keyboard configuration 
Pointer Pointer configuration 
Monitor M onitor description 

Device Graphics device description 
Screen Screen configuration 


The Files section isused to specify the default font path and the path to the RGB database. T hese paths can also be set from 
the command line (see xserver(1)). T he entries available for this section are 


FontPath "path" Sets the search path for fonts. This path is a comma-separated list of directories that the X 
server searches for font databases. M ultiple FontPath entries may be specified, and they will 
be concatenated to build up the fontpath used by the server. 


X11R6 allows the X server to request fonts from a font server. A font server is specified by 
placing a"<trans>/<hostname>:<port_number>" entry into the fontpath. For example the 
fontpath 
"/usr/X11R6/1lib/X11/fonts/misc/ ,tcp/zok:7100" 
tells the X server to first try to locatethe font in the local directory /usr/x11R6/1ib/x11/ 
fonts/misc. If that fails, then request the font from the font server running on machine zok 
listening for connections on TCP port number 7100. 

RGBPath "path" Sets the path name for the RGB color database 








The ServerFlags section is used to specify some miscellaneous X server options. The entries available for this section are 


NoTrapSignals This prevents the X server from trapping a range of unexpected fatal signals and exiting 
cleanly. Instead, the X server will dieand drop core where the fault occurred. T he default 
behavior isfor the X server exit cleanly but still drop acore file In general, you never want 
to use this option unless you are debugging an X server problem. 


DontZap This disallows the use of the C trl+AIt+B ackspace sequence T his sequence allows you to 
terminate the X server. Setting DontZap allows this key sequence to be passed to clients. 
DontZoom This disallows the use of the Ctrl+Alt-+K eypad-Plus and C trl +Alt-+k eypad-M inus sequences. 


T hese sequences allow you to switch between video modes. Setting DontZoom allows these 
key sequences to be passed to clients. 
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The Keyboard section is used to specify the keyboard input device, parameters, and some default keyboard mapping options. 
The entries available for this section are 


Protocol "kbd-protocol " kbd- protocol may beather standard Or Xqueue. Xqueue is specified when using the event 
queue driver on SVR3 or SVR4, 

AutoRepeat delay rate Changes the behavior of the autorepeat of the keyboard. T his does not work on all 
platforms. 

ServerNumLock Forces the X server to handle the numlock key internally. The X server sends a different set 
of keycodes for the numpad when the numlock key is active. T his enables applications to 
make use of the numpad. 


LeftAlt mapping RightAlt mapping AltGr mapping 
ScrollLock mapping RightCtl mapping 


Allows a default mapping to be set for the preceding keys (note that alter is a synonym for Rightalt). T he values that may be 
specified for mapping are 

Meta 

Compose 

ModeShift 

ModeLock 

ScrollLock 

Control 

The default mapping when none of these options are specified is 
LeftAlt M eta 

RightAlt M ea 

ScrollL ock C ompose 

RightC tl C ontrol 


XLeds led ... Makes! ed available for clients instead of using the traditional function (Scroll Lock, Caps 
Lock, and Num Lock). | ed isalist of numbers in the range 1 to 3. 
VTSysReq Enables the SYSV-styleVT switch sequence for non-SY SV systems that support VT 


switching. T his sequence is Alt-Sysk q followed by a function key (Fn). T his prevents the X 
server trapping the keys used for the default VT switch sequence. 


VTInit "command" Runscommand after the VT used by the server hasbeen opened. The command string is 
passed to /bin/sh -c and isrun with the real user’s!D with stdin and stdout set to the vr. 
The purpose of this option isto allow systen-dependent VT initialization commands to be 
run. One exampleis a command to disable the two-key VT switching sequence that is the 
default on some systems. 


The Pointer section is used to specify the pointer device and parameters. T he entries available for this section are 
Protocol "protocol-type" Specifies the pointer device protocol type. T he protocol types available are 


BusMouse 
Logitech 
Microsoft 
MMSeries 
Mouseman 


MouseSystems 


PS/2 
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MMHitTab 
Xqueue 
OSMouse 


Oneshould specify BusMouse for the Logitech bus mouse. Also, many newer Logitech serial mice use dther the Microsoft or 
MouseMan protocol. Xqueue should be specified here if it was used in the Keyboard section. OSMouse refers to the event-driver 
mouse interface available on SC O's SVR3. This may optionally be followed by anumber specifying the number of buttons 
the mouse has. 


Device "pointer-dev" Specifies the device the server should open for pointer input (such as /dev/ttyoo 
Or /dev/mouse). A device should not be specified when using the X queue or 
OSM ouse protocols. 

BaudRate rate Sets the baud rate of the serial mouseto rate. For micethat allow dynamic speed 
adjustments (such as Logitech), the baud rate is changed in the mouse. 

O therwise, the rate is simply set on the computer's side to allow mice with non- 
standard rates (the standard rate is 1200). 

Emulate3Buttons Enables the enulation of the third mouse button for mice that only have two 
physical buttons. The third button is enulated by pressing both buttons 
simultaneously. 

Emulate3Timeout timeout Sets the time (in milliseconds) that the server waits before deciding if two 
buttons were pressed “simultaneously” when three-button emulation is enabled. 
The default time-out is 50ms. 


ChordMiddle H andles mice that send left+right events when the middle button is used (such as 
some Logitech M ousanan mice). 

SampleRate rate Sets the number of motion/button-events the mouse sends per second. Thisis 
currently only supported for some Logitech mice 

ClearDTR This option clearstheD TR line on the serial port used by the mouse. T his 


option is only valid for a mouse using the MouseSystems protocol. Some dual- 
protocol mice require D TR to be cleared to operate in mouseSystems mode. N ote 
in versions of XFree86 prior to 2.1, thisoption also cleared theRTS line A 
separate Clearrts option has since been added for mice that require this. 

ClearRTS This option clears the RTS line on the serial port used by the mouse This option 
is only valid for a mouse using the MouseSystems protocol. Some dual-protocol 
mice require both DTR and RTS to be cleared to operate in Mousesystems mode. 
Both the cleardTR and CleararTs options should be used for such mice 


The monitor sections are used to define the specifications of a monitor and a list of video modes suitable for use with a 
monitor. M orethan onemonitor section may be present in an xF86contig file T he entries available for this section are 


Identifier "ID string" This specifies a string by which the monitor can be referred to in alater screen 
section. Each monitor section should havea unique !D string. 

VendorName "vendor " This optional entry specifies the monitor’s manufacturer. 

ModelName "model " This optional entry specifies the monitor's model. 

HorizSync horizsync-range Gives the ranges of horizontal sync frequencies supported by the monitor. 


horizsync-range May bea comma-separated list of either discrete values or ranges 
of values. A range of values is two values separated by a dash. By default, the 
values are in units of kH z. T hey may be specified in MHzorHzifMHzorHzis 
added to the end of the line The data given here is used by the X server to 
determine if video modes are within the specifications of the monitor. This 
information should be available in the monitor’s handbook. 
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VertRefresh vertrefresh-range 


Gamma gamma- values 


Mode "name " 


DotClock clock 
HTimings hdisp hsyncstart hsyncend htotal 
VTimings vdisp vsyncstart vsyncend vtotal 


Flags "flag"... 


Modeline "name" mode-description 


Gives the ranges of vertical refresh frequencies supported by the monitor. 
vertrefresh-range May bea comma-separated list of either discrete values 
or ranges of values. A range of values is two values separated by a dash. By 
default, the values are in units of Hz. They may be specified in M Hz or 
kHz if MH zor kHz is added to the end of theline The data given hereis 
used by the X server to determine if video modes are within the 
specifications of the monitor. Thisinformation should be availablein the 
monitor’s handbook. 

This is an optional entry that can be used to specify the gamma 
correction for the monitor. It may be specified as athe a single value or 
as three separate RGB values. N ot all X servers are capable of using this 
information. 

Indicates the start of a multi-line video mode description. The mode 
description is terminated with an End-M ode line The mode description 
consists of the following entries: 

The dot clock rate to be used for the mode. 

Specifies the horizontal timings for the mode. 

Specifies the vertical timings for the mode 

Specifies an optional set of mode flags. interlace indicates that the mode 
is interlaced. DoubleScan indicates a mode where each scanline is doubled. 
+HSync and -HSync can be used to select the polarity of the H Sync signal. 
+vSync and -vSync can be used to sdect the polarity of the V Sync signal. 
Composite can be used to specify composite sync on hardware where thisis 
supported. Additionally, on some hardware, +csync and -csync may be 
used to sdect the composite sync polarity. 

A single line format for specifying video modes. Themode- description is 
in four sections, the first three of which are mandatory. The first is the 
pixd clock. Thisis a single number specifying the pixd clock rate for the 
mode The second section is a list of four numbers specifying the 
horizontal timings. T hese numbers are the hdisp, hsyncstart, hsyncend, 
htotal. T hethird section isa list of four numbers specifying the vertical 
timings. These numbers are vdisp, vsyncstart, vsyncend, vtotal. The final 
section isa list of flags specifying other characteristics of the mode. 
Interlace indicates that the mode is interlaced. DoubleScan indicates a 
mode where each scanline is doubled. +HSync and -Hsync can be used to 
select the polarity of thexsync signal. +vsync and -vsync can be used to 
select the polarity of the vsync signal. Composite can be used to specify 
composite sync on hardware where this is supported. Additionally, on 
some hardware, +csync and -csync may be used to select the composite 
sync polarity. 


The Device sections are used to define a graphics device (video board). M orethan one Device section may be present in an 
xF86contig file. The entries available for this section are 


Identifier "ID string" 


VendorName "vendor" 
BoardName "model " 


Chipset "chipset-type" 


This specifies a string by which the graphics device can be referred to ina 
later Screen section. Each Device section should havea unique !D string. 


This optional entry specifies the graphics device's manufacturer. 
This optional entry specifies the name of the graphics device 


This optional entry specifies the chipset used on the graphics board. In 
most cases, this entry is not required because the X servers will probe the 
hardware to determine the chipset type. 
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Ramdac "ramdac-type" This optional entry specifies the type of RAM DAC used on the graphics board. 
This is only used by afew of the X servers, and in most cases, it is not required 
because the X servers will probe the hardware to determine the RAM DAC type 
where possible. 

DacSpeed speed This optional entry specifies the RAM DAC speed rating (which is usually 
printed on the RAM DAC chip). The speed isin M Hz. Thisis only used by a 
few of the X servers and only needs to be specified when the speed rating of the 
RAM DAC isdifferent from the default built in to the X serve. 


Clocks clock ... Specifies the dotclocks that are on your graphics board. T he clocks arein MHz 
and may be specified as a floating-point number. T he value is stored internally to 
the nearest KH z. The ordering of the clocks is important. It must match the 
order in which they are sdected on the graphics board. M ultiple clocks lines may 
be specified. For boards with programmable clock chips, the clockchip entry 
should be used instead of this. A clocks entry isnot mandatory for boards with 
non-programmable clock chips but is highly recommended because it prevents 
the clock probing phase during server startup. This clock probing phase can 
cause problems for some monitors. 


ClockChip "clockchip-type” This optional entry is used to specify the clock chip type on graphics boards that 
havea programmable clock generator. O nly a few X servers support program- 
mable clock chips. For details, see the appropriate X server manual page. 

ClockProg command [textclock] This optional entry runscommand to set the clock on the graphics board instead of 
using the internal code. The command string must consist of the full pathname 
(and no flags). W hen using this option, aclocks entry is required to specify 
which clock values are to be made available to the server (up to 128 clocks may 
be specified). The optional textclock valueis to tell the server that command must 
berun to restore the text-mode clock at server exit (or when VT switching). 
textclock Must match one of the valuesin theciocks entry. This parameter is 
required when the clock used for text mode is a programmable clock. 

The command is run with the real user’s 1D with stdin and stdout set to the 
graphics console device. T wo arguments are passed to the command. The first is 
the clock frequency in M Hz asa floating-point number and the second is the 
index of the clock in the clocks entry. The command should return an exit status 
of 0 when successful and something in the range 1-254 otherwise. 

Thecommand isrun when the initial graphics mode is set and when changing 
screen resolution with the hotkey sequences. If the program fails at initialization, 
the server exits. If it fails during a mode switch, the mode switch is aborted but 
the server keeps running. It is assumed that if the command fails, the clock has 
not been changed. 

Option optionstring This optional entry allows the user to select certain options provided by the 
drivers. M ultiple option entries may be given. The supported values for 
optionstring aregiven in the appropriate X server manual pages. 

VideoRam mem This optional entry specifies the amount of video RAM that isinstalled on the 
graphics board. T his is measured in kilobytes. In most cases, thisis not required 
because the X server probes the graphics board to determine this quantity. 

BIOSBase baseaddress This optional entry specifies the base address of the video BIOS for the VGA 
board. T his address is usually 0xC 0000, which is the default the X servers use. 
Some systems, particularly those with on-board VGA hardware, have the BIOS 
located at an alternate address, usually 0xE0000. If your video BIOS is at an 
address other than 0xC 0000, you must specify the base address in the xFseconfig 
file. N ote that some X servers don’t access the BIOS at all and those that do only 
use the BIOS when searching for information during the hardware probe phase. 





Part V: FileFormats 


MemBase baseaddress 


I0Base baseaddress 
DACBase baseaddress 
POSBase baseaddress 


COPBase baseaddress 





VGABase baseaddress 


Instance number 


Speedup selection 


S3MNAdjust MN 


S3MC1k clock 


S3RefClock clock 


This optional entry specifies the memory base address of a graphics board’s linear 
frame buffer. T his entry is only used by afew X servers, and the interpretation of 
this base address may be different for different X servers. Refer to the appropriate 
X server manual page for details. 

This optional entry specifies the |O base address. This entry is only used for a 
few X servers. Refer to the appropriate X server manual page for details. 

This optional entry specifies the DAC base address. T his entry is only used for a 
few X servers. Refer to the appropriate X server manual page for details. 

This optional entry specifies the PO S base address. T his entry is only used for a 
few X servers. Refer to the appropriate X server manual page for details. 

This optional entry specifies the coprocessor base address. T his entry is only used 
for afew X servers. Refer to the appropriate X server manual page for details. 
This optional entry specifies the VGA memory base address. T his entry is only 
used for a few X servers. Refer to the appropriate X server manual page for 
détails. 
This optional entry specifies the instance (which indicates if the chip is 

integrated on the motherboard or on an expansion card). T his entry is only used 
for afew X servers. Refer to the appropriate X server manual page for details. 
This optional entry specifies the selection of soeedups to be enabled. This entry 
is only used for a few X servers. Refer to the appropriate X server manual page for 
détails. 
This optional entry is specific to the S3 X server. For details, refer to the 
XF86_S3(1) Manual page. 
This optional entry is specific to the S3 X server. For details, refer to the 
XF86_S3(1) Manual page. 
This optional entry is specific to the S3 X server. For details, refer to the 
XF86_$3(1) Manual page. 














The screen sections are used to specify which graphics boards and monitors are used with a particular X server and the 
configuration in which they are to be used. T he entries available for this section are 


Driver driver-name 


Device device-id 
Monitor monitor-id 


ScreenNo scrnum 








Each screen section must begin with a Driver entry, and thedriver-name given in 
each Screen section must be unique. The driver-name determines which X server 
(or driver type within an X server when an X server supports more than one 
head) reads and uses a particular screen section. The driver names available are 


Accel 

Mono 

SVGA 

VGA2 

VGA16 

Accel iS used by all the accderated X servers (see xF86_Accel(1)). Mono is used by 
thenon-VGA mono drivers in the 2-bit and 4-bit X servers (see XF86_Mono(1) and 
XF86_VGA16(1)), vaa2 and veaie are used by the VGA drivers in the 2-bit and 4-bit 
X servers. svea is used by the xF86_svGa X server. 

Specifies which graphics device description isto be used. 

Specifies which monitor description is to be used. 


This optional entry overrides the default screen numbering in a multi-headed 
configuration. T he default numbering is determined by the ordering of the 
Screen sections in the xF8éconfig file. T o override this, all relevant screen 
sections must have this entry specified. 
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BlankTime ti me Sets the inactivity time-out for the blanking phase of the screensaver. time isin 
minutes, and the default is 10. T his is equivalent to the X server's -s flag, and the 
value can be changed at runtime with xset(1). 


SuspendTime ti me Sets the inactivity time-out for the “suspend” phase of the screensaver. time isin 
minutes, the default is 15, and it can be changed at runtime with xvidtune(1). This 
isonly suitable for VESA DPM S compatible monitors and is only supported 
currently by some X servers. The “power_saver” Option must be set for this to be 
enabled. 


OffTime time Sets the inactivity time-out for the “off” phase of the screensaver. ti me isin minutes, 
the default is 30, and it can be changed at runtime with xvidtune(1). T hisis only 
suitable for VESA DPM S compatible monitors and is only supported currently by 
some X servers. The “power_saver” Option must be set for this to be enabled. 

SubSection Display This entry isa subsection that is used to specify some display specific parameters. 
This subsection is terminated by an EndSubSection entry. For some X servers and 
drivers (those requiring a list of video modes), this subsection is mandatory. For X 
servers that support multiple display depths, more than one Display subsec-tion can 
be present. When multiple Display subsections are present, each must havea unique 
Depth entry. T he entries available for the Display subsection are 


Depth bpp This entry is mandatory when morethan one Display subsection is present in a 
Screen section. W hen only one Display subsection is present, it specifies the default 
deoth where the X server will run. W hen more than one Display subsection is 
present, the depth determines which gets used by the X server. The subsection used 
is the one matching the depth at which the X server is run. Not all X servers (or 
drivers) support morethan one depth. Permitted valuesforbpp ares, 15, 16, 24, and 
32. Not all X servers (or drivers) support all these values. bpp values of 24 and 32 are 
treated equivalently by those X servers that support then. 

Weight RGB This optional entry specifies the rdative RGB weighting to be used for an X server 
running at 16bpp. T his may also be specified from the command line (see 
xFrees6(1)). Values supported by most 16bpp X servers are 555 and 56s. For further 
details, refer to the appropriate X server manual page 

Virtual xdim ydim This optional entry specifies the virtual screen resolution to be used. xdi m must bea 
multiple of ther 8 or 16 for most color X servers and a multiple of 32 for the 
monochrome X server. The given value is rounded down if this is not the case. For 
most X servers, video modes that are too large for the specified virtual size are 
rejected. If this entry is not present, the virtual screen resolution is set to accommo- 
date all the valid video modes given in the modes entry. Some X servers do not 
support this entry. Refer to the appropriate X server manual pages for details. 

ViewPort x0 y0 This optional entry sets the upper-left corner of the initial display. T hisis only 
relevant when the virtual screen resolution is different from the resolution of the 
initial video mode. If this entry is not given, then the initial display is centered in the 
virtual display area. 

Modes modename ... This entry is mandatory for most X servers, and it specifies the list of video modes to 
use. The video mode names must correspond to those specified in the appropriate 
Monitor section. M ost X servers delete modes from this list that don’t satisfy various 
requirements. T he first valid mode in this list is the default display mode for startup. 
The list of valid modes is converted internally into a circular list. It is possible to 
switch to the next mode with C trl+Alt+k eypad Plus and to the previous mode with 
Ctrl+Alt+K eypad M inus. 

InvertVCLK modename Q!1 This optional entry is specific to the S3 server only. It can be used to change the 
default VCLK invert/non-invert state for individual modes. If "modename"is"", the 
setting applies to all modes unless overridden by later entries. 
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EarlySC modename Q;1 


BlankDelay modename valuel value2 


Visual visual-name 


Option optionstring 


Black red green blue 


White red green blue 


This optional entry is specific to the S3 server only. It can be used to change the 
default Ear1ysc setting for individual modes. T his setting can affect screen wrapping. 
If "modename" iS"", thesetting applies to all modes unless overridden by later entries. 


This optional entry is specific to the S3 server only. It can be used to change the 
default blank delay settings for individual modes. This can affect screen wrapping. 
valuel and value2 must be integers in the range 0-7. If "modename" is", thesetting 
applies to all modes unless overridden by later entries. 


This optional entry sets the default root visual type This can also be specified from 
the command line (see Xserver(1)). T he visual types available for 8bpp X servers are 
(default is PseudoColor): 


StaticGray 

GrayScale 

StaticColor 

PseudoColor 

TrueColor 

DirectColor 

The visual type available for the 16bpp and 32bpp X serversis TrueColor. 
The visual type available for the bpp X server is staticGray. 

The visual types available for the 4bpp X server are (default is PseudoColor): 
StaticGray 

GrayScale 

StaticColor 

PseudoColor 

This optional entry allows the user to select certain options provided by the drivers. 


M ultiple option entries can be given. The supported values for option-string are 
given in the appropriate X server manual pages. 


This optional entry allows the “black” color to be specified. T his is only supported 
with the VGA2 driver in the xF86_Mono server (for details, see XF86_Mono(1)). 
This optional entry allows the “white” color to be specified. This is only supported 
with the VGA2 driver in the xF86_Mono server (for details, see XF86_Mono(1)). 








For an example of an xFséconfig file, see the file installed as <xRoot>/1ib/X11/XF86Config.eg. 


FILES 


/etc/XF86Conf ig 


<XRoot>/1ib/X11/XF86Config. hostname <XRoot>/lib/X11/XF86Config 


N ote that <xroot> refers to the root of the X11 install tree. 


SEE ALSO 


x(1), Xserver(1), xFrees86(1), xF86_SvGA(1), xF86_vGA16(1), XF86_Mono(1), xF86_S3(1), xF86_8514(1), XxF86_Macha(1), 
XF86_Mach32(1), xF86_p9000(1), xF86_AGX(1), xF86_w32(1) 


AUTHORS 


Refer to the xFrees6(1) manual page. 
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intro 
intro— Introduction to games. 
DESCRIPTION 
This chapter describes all the games and funny little programs available on the system. 
AUTHORS 
Look at the header of the manual page for the authors and copyright conditions. N ote that these can be different from page 
to page! 
Linux, 24 July 1993 
banner 
banner— Print large banner on printer. 
SYNOPSIS 
/usr/games/banner [ -wn ] message ... 
DESCRIPTION 


banner prints a large, high-quality banner on the standard output. If the message is omitted, it prompts for and reads oneline 
of its standard input. If -w is given, the output is scrunched down from a width of 132 to n, suitable for a narrow terminal. If 
nisomitted, it defaults to se. 


The output should be printed on a hard-copy device, up to 132 columns wide with no breaks betwee the pages. T he 
volumeis great enough that you might want a printer or a fast hard-copy terminal, but if you are patient, a decwriter or 
other 300 baud terminal will do. 


BUGS 


Several ASCII characters are not defined, notably <, >, [, ],\, *,_, {,}, |, and ~. Also, the characters ", ', and a are funny- 
looking (but in a useful way). 


The -w option isimplemented by skipping some rows and columns. T hesmaller it gets, the grainier the output. Sometimes it 
runs letters together. 


AUTHOR 
M ark H orton 
6 June1993 


ddate 


ddate— Converts boring normal dates to fun D iscordian dates. 


SYNOPSIS 


ddate 


ddate Eg 


DESCRIPTION 


ddate prints the date in D iscordian date format. 


AUTHOR 


Druel the Chaotic, ak.a. Jeremy Johnson (mpython@gnu.ai.mit.edu). M odifications for UNIX by LeeH arvey O swald Smith, 
K.S.C. Five tons of flax. 
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intro 


intro— Introduction to miscdlany section. 


DESCRIPTION 


This chapter describes miscellaneous things such aS nroff macro packages, tables, C header files, the file hierarchy, general 
concepts, and other things that don’t fit anywhere else. 


AUTHORS 


Look at the header of the manual page for the authors and copyright conditions. N ote that these can be different from page 
to page! 


Linux, 23 April 1993 


ascll 

ascii— The ASCII character set encoded in octal, decimal, and hexadecimal 
DESCRIPTION 

The following table contains the 128 ASCII characters. 

C program ‘\X’ escapes are noted. 


Oct Dec H e&x Char Oct Dec H e&x Char 
000 0 00 NUL ‘\0’ 100 64 40 @ 
001 1 01 SOH 101 65 41 A 
002 2 02 STX 102 66 42 B 
003 3 03 ETX 103 67 43 C 
004 4 04 EOT 104 68 44 D 
005 5 05 ENQ 105 69 45 E 
006 6 06 ACK 106 70 46 F 
007 7 07 BEL ‘\a’ 107 71 47 G 
010 8 08 BS ‘\b’ 110 72 48 H 
011 9 09 HT ‘\t’ 111 73 49 | 
012 10 0A LF ‘\n’ 112 74 4A J 
013 ll OB VT \v 113 75 4B K 
014 12 0c FF ‘\f’ 114 76 4c L 
015 13 0D CR ‘\r’ 115 77 4D M 
016 14 OE SO 116 78 4E N 
017 15 OF Sl 117 79 4F 0 
020 16 10 DLE 120 80 50 P 
021 17 11 DCl 121 81 51 Q 
022 18 12 DC2 122 82 52 R 
023 19 13 DC3 123 83 53 S 
024 20 14 DC4 124 84 54 T 
025 21 15 NAK 125 85 55 U 
026 22 16 SYN 126 86 56 V 


accii 


Char 


H ex 


57 


Dec 
87 
88 
89 
90 


Oct 


Char 
ETB 


H ex 
17 
18 
19 
1A 
1B 
1c 
1D 
1E 
1F 


Dec 
23 
24 
25 
26 
27 
28 
29 
30 
31 


Oct 





127 
130 
131 
132 
133 
134 
135 
136 
137 
140 
141 
142 
143 
144 
145 
146 
147 
150 
151 
152 
153 
154 
155 
156 
157 
160 
161 
162 
163 
164 
165 
166 
167 
170 
171 
172 
173 
174 
175 
176 
177 


027 
030 
031 
032 
033 
034 
035 
036 
037 
040 
041 
042 
043 
044 
045 
046 
047 
050 
051 
052 
053 
054 
055 
056 
057 
060 
061 
062 
063 
064 
065 
066 
067 
070 
071 
072 
073 
074 
075 
076 
077 


58 
59 


CAN 
EM 


5A 
5B 
5C 


SUB 


91 


ESC 
FS 
GS 


\\V" 


92 


5D 
5E 


93 
94 
95 
96 
97 


RS 


5F 


US 


60 


SPACE 


20 
21 
22 
23 


32 


61 


33 
34 
35 
36 
37 


62 


98 
99 


63 
64 
65 
66 
67 


100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 


24 
25 
26 
27 
28 
29 


% 


38 
39 
40 


68 
69 


41 


6A 
6B 
6C 


2A 
2B 
2C 


42 


43 


44 
45 


6D 
6E 


2D 
2E 
2F 


46 


6F 


47 


70 
71 


30 


48 


31 


49 


72 


32 


50 
51 


73 
74 
75 
76 
77 
78 
719 


33 


34 
35 
36 
37 


52 


53 
54 
55 
56 
57 


38 
39 


TA 
7B 
7C 


3A 
3B 
3C 


58 
59 
60 
61 


— a2 


7D 
TE 


3D 
3E 


62 


DEL 


TF 


3F 


63 
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HISTORY 
An ascii manual page appeared in version 7 AT&T UNIX. 


SEE ALSO 
iso_8859 1(7) 


Linux 


bootparam 


bootparam— Introduction to boot-time parameters of the Linux kernd. 


DESCRIPTION 


The Linux kernd accepts certain command-line options or boot-time parameters at the moment it is started. In general, this 
is used to supply the kernel with information about hardware parameters that the kernel would not be ableto determine on 
its own, or to avoid or override the values that the kernel would otherwise detect. 


When the kernel is booted directly by the BIOS (say, from a floppy to which you copied a kernel using cp zImage /dev/fde), 
you have no opportunity to specify any parameters. To take advantage of this possibility, you have to use software that is able 
to pass parameters, such as LILO or loadlin. For a few parameters, one can also modify the kernel image itsef, using rdev; see 
rdev(8) for further details. 


TheLILO program (LInux LO ade) written by Werner Almesberger is the most commonly used. It has the ability to boot 
various kernels and stores the configuration information in a plain text file (See 1i10(8) and 1ilo.conf(5).) LILO can boot 
DOS, 0S/2, Linux, FreeBSD , and so on and is quite flexible. 


The other commonly used Linux loader is loadlin, which isa DOS program that has the capability to launch a Linux kernd 
from the DO S prompt (with boot args) assuming that certain resources are available. This is good for people who want to 
launch Linux from DOS. 


It isalso very useful if you have certain hardware that relies on the supplied DOS driver to put the hardware into a known 
state. A common example is SoundBlaster-compatible sound cards that require the D OS driver to twiddle a few mystical 
registers to put the card into a SB-compatible mode. Booting DO S with the supplied driver and then loading Linux from the 
DOS prompt with loadlin avoids the reset of the card that happens if one reboots instead. 


THE ARGUMENT LIST 
M ost of the boot args take the form of 


name[=value_l][,value 2]...[,value_ 11] 


name iS a unique Keyword that is used to identify what part of the kernd the associated values (if any) are to be given to. 

M ultiple boot args are just a space-separated list of the preceding format. N ote the limit of 11 is real because the present code 
handles only 11 comma-separated parameters per keyword. (H owever, you can reuse the same keyword with up to an 
additional 11 parameters in unusually complicated situations, assuming the setup function supports it.) 


M ost of the sorting occurs in linux/init/main.c. First, the kernel checks to see if the argument is any of the special 
arguments root=, ro, rw, OF debug. The meaning of these special arguments is described later in the document. 


Then, it walks a list of setup functions (contained in the bootsetups array) to see if the specified argument string (such as foo) 
is associated with a setup function (foo_setup()) for a particular device or part of the kernel. If you passed the kernel the line 
foo=3,4,5,6, then the kernal searches the bootsetups array to seeif foo is registered. If it is, it calls the setup function 
associated with foo (foo_setup()) and handsit the arguments 3, 4, 5, and 6 aSgiven on the kernel command line. 


Anything of the form foo=bar that is not accepted as a setup function as described is then interpreted as an environment 
variable to be set. A (useless?) example is to use TERM=vt100 as a boot argument. 
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Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then 
passed onto process one which is usually the init program. The most common argument that is passed to the init process is 
the word single, which instructs init to boot the computer in single user mode and not launch all the usual daemons. C heck 
the manual page for the version of init installed on your system to see what arguments it accepts. 


GENERAL NON-DEVICE-SPECIFIC BOOT ARGS 


no387 
Somei387 coprocessor chips have bugs that show up when used in 32-bit protected mode 
For example, some of the early ULSI-387 chips cause solid lockups while performing floating-point calculations. U sing the 
'no387' boot arg causes Linux to ignore the maths coprocessor even if you have one Of course, you must then have your 
kernd compiled with math enulation support! 

no-hlt 


Some of the early i486D X-100 chips have a problen with the hit instruction in that they can’t reliably return to operating 
modeafter this instruction isused. Using the 'no-hit' instruction tals Linux to just run an infiniteloop when there is 
nothing dse to do and to not halt the CPU. This allows people with these broken chips to use Linux. 


root=... 
This argument tells the kernel what device isto be used as the root filesystem while booting. T he default of this setting is 
determined at compile time and usually is the value of the root device of the system that the kernel was built on. To override 
this value and select the second floppy drive as the root device one uses 'root=/dev/fd1'. (The root device can also be set 
using rdev(8).) 
The root device can be specified symbolically or numerically. A symbolic specification hasthe form /dev/xxyn, where xx 
designates the device type (ha for ST -506-compatible hard disk with y in a-h; sd for SC Sl-compatible disk with y in a-e; xa 
for XT -compatible disk with y either a or b; fd for floppy disk with y the floppy drive number— faa isthe DOS A: drive and 
fd1 iSB:), Y isthe driver letter or number, and v isthe number of the partition on this device (absent in the case of floppies). 
N ote that this has nothing to do with the designation of these devices on your filesystem. The /dev/ part is purely conven- 
tional. 
The more awkward and less portable numeric specification of the previous possible root devices in major/minor format is 
also accepted. (For example, /dev/sda3 is major 8, minor 3, SO you Can US@ root=0x803 as an alternative) 


ro and rw 


The ro option tdls the kernel to mount the root filesystem as readonly so that filesystem consistency check programs (fsck) 
can do their work on a quiescent file system. N 0 processes can write to files on the filesystem in question until it is re 
mounted as read/write capable, such as by mount -w -n -o remount /. (See also mount(8).) 


The rw option tells the kernel to mount the root filesysten read/write. T his is the default. 
The choice between read-only and read/write can also be set usingrdev(8). 
debug 


Kernd messages are handed off to the kernel log daemon k1oga so that they can be logged to disk. M essages with a priority 
above console_loglevel are also printed on the console (For these levds, see<linux/kernel.h>.) By default, this variable is set 
to log anything more important than debug messages. T his boot argument causes the kernel to also print the messages of 
peBuc priority. The console log level can also be set at runtime via an option to klogd. See klogd(8). 


reserves... 


This is used to protect I/O port regions from probes. The form of the command is 


reserve=i obase,extent[,iobase,extent ]... 


Part VII: Miscdlaneous 


In some machines, it might be necessary to prevent device drivers from checking for devices (auto-probing) in a specific 
region. T his may be because of hardware that reacts badly to the probing, hardware that would be mistakenly identified, or 
hardware you don’t want the kernd to initialize 


The reserve boot-time argument specifies an |/O port region that shouldn’t be probed. A device driver does not probea 
reserved region unless another boot argument explicitly specifies that it do so. 

For example, the boot line 

reserve=0x300 ,32 blah=0x300 

keeps all device drivers except the driver for blah from probing 0x300-0x31f. 

ramdisk=.. 

This option is obsolete since Linux 1.3.48 or so. It specifies the size in kilobytes of the optional RAM disk device For 
example, if one wants to have a root filesystem on a 1.44M B floppy loaded into the RAM disk device they use 
ramdisk=1440 


This option is set at compile time (default isno RAM disk), and can be modified using rdev(8). 
mem=... 


TheBIOS call defined in the PC specification that returns the amount of installed memory was only designed to be able to 
report up to 64M B. Linux uses this BIO S call at boot to determine how much memory is installed. If you have more than 
64M B of RAM installed, you can use this boot arg to tell Linux how much memory you have. The value is in decimal or 
hexadecimal (prefix Ox), and the suffixes k (times 1024) or m (times 1048576) can be used. The following quote from Linus 
describes the use of the mem= parameter: 


“Thekernd will accept any mem=xx parameter you giveit, and if it turns out that you lied to it, it will crash horribly sooner or 
later. The parameter indicates the highest addressable RAM address, so 'mem=0x1000000' means you have 16M B of memory, 
for example. For a96M B machine this would be mem=ex60e00000. 

NOTE: Some machines might use the top of memory for BIOS caching or whatever, so you might not actually have up to 
the full 96M B addressable. T he reverse is also true: Some chipsets will map the physical memory that is covered by the BIOS 
area into the area just past the top of memory, so the top-of-mem might actually be 96M B +384KB, for example. If you tell 
Linux that it has more memory than it actually does have, bad things will happen: maybe not at once, but surdy eventually.” 


reboot =warm 


Since 2.0.22, areboot is by default a cold reboot. Thiscommand-line option changes back to the old default, a warm reboot. 


BOOT ARGUMENTS FOR SCSI DEVICES 
General notation for this section: 


iobase— thefirst |/O port that the SCSI host occupies. T heseare specified in hexadecimal notation and usually liein the 
range from 0x200 to Ox3ff. 


irq— the hardware interrupt that the card is configured to use Valid values are dependent on the card in question but are 
usually 5, 7, 9, 10, 11, 12, and 15. The other values are usually used for common peripherals such asIDE hard disks, floppies, 
serial ports, and so on. 


scsi-id—thelD that the host adapter uses to identify itsdf on the SCSI bus. O nly some host adapters allow you to change 
this value because most have it permanently specified internally. The usual default valueis7, but the Seagate and Future 
Domain TM C-950 boards use 6. 


parity— whether theSC Sl host adapter expects the attached devices to supply a parity value with all information exchanges. 
Specifying a1 indicates parity checking is enabled, and ae disables parity checking. Again, not all adapters support selection 
of parity behavior as a boot argument. 
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A SCSI devicecan havea number of subdevices contained within itself. The most common example is one of the new SCSI 
CD-ROMs that handle more than one disk at atime Each CD is addressed as a Logical Unit N umber (LUN ) of that 
particular device. M ost devices, such as hard disks and tape drives, are only one device and are assigned to LUN o. 


Some poorly designed SC SI devices cannot handle being probed for LU N s not equal to a. Therefore, if the compile time flag 
CONFIG SCSI MULTI LUN iSnot set, newer kernds by default only probe LUN oa. 


max_scsi_luns=... 


To specify the number of probed LUN sat boot, oneenters max scsi luns=n aSa boot arg, wheren isanumber between 1 
and 8. To avoid problems as described, one uses n=1 to avoid upsetting such broken devices. 


SCS! TAPE CONFIGURATION 
Some boot-time configuration of the SC SI tape driver can be achieved with the following: 
st=buf size[,write threshold[,max_bufs ]] 
The first two numbers are specified in units of kilobytes. The default buf size is32KB, and the maximum size that can be 
specified is a ridiculous 16384KB. Thewrite_threshold isthe value at which the buffer is committed to tape with a default 
value of 30KB. The maximum number of buffers varies with the number of drives detected and has a default of two. A 
sample usage is 
st=32,30,2 


Full details can be found in the Reape .st file that isin the scsi directory of the kernd source tree. 


ADAPTEC AHA151X, AHA152X, AIC6260, AIC 6360, $B16-SCSI CONFIGURATION 
The aha numbers refer to cards and the aic numbe’s refer to the actual SC SI chip on these types of cards, including the 
SoundBlaster-16 SCSI. 
The probe code for these SC SI hosts looks for an installed BIOS, and if noneis present, the probe will not find your card. 
Then you must use a boot arg of the form: 
aha152x=i obase[,irg[,scsi-id[,reconnect [,parity]]]] 


If the driver was compiled with debugging enabled, a sixth value can be specified to set the debug levd. 


All the parameters are as described at the top of this section, and the reconnect value allows device disconnect/reconnect if a 
nonzero value is used. A sample usage is as follows: 
aha152x=0x340,11,7,1 


N ote that the parameters must be specified in order, meaning that if you want to specify a parity setting, then you must 
specify aniobase,irq,scsi-id, aNdreconnect valueas wall. 


ADAPTEC AHA154X CONFIGURATION 


The ahal542 series cards have an i82077 floppy controller on board, whereas the ana1540 series cards do not. T hese are bus- 
mastering cards and have parameters to set the “fairness” that is used to share the bus with other devices. The boot arg looks 
like the following: 


aha1542=i obase[,buson ,busoff [,dmaspeed ]] 


Valid i obase values are usually one of 0x130, 0x134, 0x230, 0x234, 0x330, Or 0x334. Clone cards may permit other values. 


Thebuson and busoff values refer to the number of microseconds that the card dominates the SA bus. T he defaults are 11us 
on and 4us off so that other cards (such as an ISA LAN CE Ethernet card) havea chance to get access to the ISA bus. 


Thedmaspeed value refers to the rate (in M B/s) at which the DM A (Direct M emory Access) transfers proceed. The default is 
5M B/s. N ewer revision cards allow you to select this value as part of the soft-configuration; older cards use jumpers. You can 
use values up to 10M B/s, assuming that your motherboard is capable of handling it. Experiment with caution if using values 
over 5M B/s. 
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ADAPTEC AHA274X, AHA284X, AIC7XXX CONFIGURATION 
T hese boards can accept an argument of the form: 
aic7xxx=extended,no_reset 
The extended value, if nonzero, indicates that extended translation for large disksis enabled. Theno_reset value, if nonzero, 
tells the driver not to reset the SC SI bus when setting up the host adapter at boot. 
BUSLOGIC SCSI HOSTS CONFIGURATION (buslogic=) 
At present, the buslogic driver accepts only one parameter, the!/O base. It expects that to be one of the following valid 
ValU@S: 0x130, 0x134, 0x230, 0x234, 0x330, OF 0x334. 
FUTURE DOMAIN TMC-8XX, TMC-950 CONFIGURATION 
If your card is not detected at boot time you must use a boot arg of the form 
tmc8xx=mem_base,irq 
Themem base value is the value of the memory-mapped I/O region that the card uses. This is usually one of the following 
ValUES: 0xc8000, 0xca000, Oxcc000, Oxced00, Oxdc0O0, OF Oxdeo09. 
PRO AUDIO SPECTRUM CONFIGURATION 
The PAS16 uses an NC 5380 SCSI chip, and newer modes support jumperless configuration. The boot arg is of the form 
pas16=i obase irq 
The only difference is that you can specify an IRQ value of 255, which tells the driver to work without using interrupts, 
albat at a performance loss. Thei obase is usually ox3ss. 
SEAGATE ST-0X CONFIGURATION 
If your card is not detected at boot time you must use a boot arg of the form 
stOx=mem_base irq 
Themem base value is the value of the memory-mapped I/O region that the card uses. This is usually one of the following 
ValUES: 0xc8000, 0xca000, Oxcc000, Oxce000, Oxdc0O0, OF Oxdeo09. 
TRANTOR T128 CONFIGURATION 
T hese cards are also based on the N CR5380 chip and accept the following options: 
t128=mem_base ,irg 


The valid values for mem base areas follows: oxcc000, 0xc8000, @xdc000, and oxd8000. 


CARDS THAT DON'T ACCEPT BOOT ARGS 


At present, the following SC SI cards do not make use of any boot-time parameters. In some cases, you can hard-wire values 
by directly editing the driver itself, if required. 


Always IN 2000, Adaptec ahal740, EAT A-D MA, EATA-PIO, Future D omain 16xx, N CR5380 (generic), NCR53c7xx to 
NCR53c8xx, Q logic, Ultrastor (including u?4f), and Western Digital wd7000. 
HARD DISKS 


IDE DISK/CD-ROM DRIVER PARAMETERS 


ThelDE driver accepts anumber of parameters, which rangefrom disk geometry specifications to support for broken 
controller chips. D rive specific options are specified by using hax= with x in a-h. 


N on-drive- specific options are specified with the prefix nd=. N ote that using a drive-specific prefix for a non-drive- specific 
option will still work, and the option will just be applied as expected. 
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Also note that hd= can be used to refer to the next unspecified drivein the (a, .., h) sequence. For the following discussions, 
the hd= option will be cited for brevity. See the file README. ide in linux/drivers/block for more details. 
THEhd=cyls, heads ,sects[ ,wpcom[ ,irq]] OPTIONS 
T hese options are used to specify the physical geometry of the disk. O nly the first three values are required. The cylinder, 
head, and sectors values are those used by fdisk. T he write precompensation value is ignored for IDE disks. TheIRQ value 
specified isthe!RQ used for the interface that the drive resides on and is not really a drive specific parameter. 
THE hd=serialize OPTION 
The dual IDE interface C M D -640 chip is broken as designed such that when drives on the secondary interface are used at 
the same time as drives on the primary interface, it will corrupt your data. U sing this option tells the driver to make sure that 
both interfaces are never used at the same time 
THE hd=dtc2278 OPTION 
This option tells the driver that you havea DT C-2278D IDE interface. The driver then tries to do D TC-specific operations 
to enable the second interface and to enable faster transfer modes. 
THE hd=noprobe OPTION 
Do not probe for this drive The following line 
hdb=noprobe hdb=1166,7,17 


disables the probe but still specifies the drive geometry so that it is registered as a valid block device and hence usable. 


THE hd=nowerr OPTION 
Some drives apparently have thewrerr stat bit stuck on permanently. T his enables a work-around for these broken devices. 


THE hd=cdrom OPTION 
Thistellsthe IDE driver that thereis an ATAPI compatibleCD-ROM attached in place of anormal IDE hard disk. In most 
cases, theC D-ROM isidentified automatically, but if it isn’t, then this might help. 

STANDARD ST-506 DISK DRIVER OPTIONS (hd=) 


The standard disk driver can accept geometry arguments for the disks similar to the IDE driver. N ote however that it only 
expects three values (c/H/s); any more or any less and it will silently ignore you. Also, it only accepts ha= as an argument; hda= 
and so on are not valid here. The format is as follows: 


hd=cyls ,heads ,sects 
If there are two disks installed, the preceding line is repeated with the geometry parameters of the second disk. 


XT DISK DRIVER OPTIONS (xd=) 


If you are unfortunate enough to be using one of these old 8-bit cards that move data at a whopping 125K B/s, then hereis 
the scoop. If the card is not recognized, you must use a boot arg of the form 


xd=type,irq,iobase,dma_chan 


Thetype value specifies the particular manufacturer of the card, and you use one of the following: o=geeric, 1=DTC, 2, 3, 
4=W estern D igital, 5, 6, 7=Seagate, or s=O M TI. The only difference between multiple types from the same manufacturer is 
the BIOS string used for detection, which is not used if the type is specified. 


The xd_setup() function does no checking on the values and assumes that you entered all four values. D on’t disappoint it. 
H ereisasample usage for aWD 1002 controller with the BIOS disabled or renoved, using the default XT controller 
parameters: 


xd=2,5,0x320,3 
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CD-ROMS (NON-SCSI/ATAPI/IDE) 


THE AZTECH INTERFACE 
The syntax for this type of card is 


aztcd=i obase[,magic_number ] 


If you set the magi c_number to @x79, the driver will run anyway in the event of an unknown firmware version. All other values 
are ignored. 


THE CDU-31A AND CDU-33A SONY INTERFACE 


ThisCD-ROM interfaceis found on some of the Pro Audio Spectrum sound cards and other Sony supplied interface cards. 
The syntax is as follows: 


cdu3ta=i obase,[irg[,is_pas_card]] 


Specifying an IRQ value of o tells the driver that hardware interrupts aren't supported (as on some PAS cards). If your card 
supports interrupts, you should use them because they cut down on theC PU usage of the driver. 


Theis_pas_card should be entered as pas if using aPro Audio Spectrum card; otherwise, it should not be specified at all. 
THE CDU-535 SONY INTERFACE 


The syntax for this CD-ROM interface is 
sonycd535=i obase[,irq] 


A @ca beused for the!/O base asa placeholder if you want to specify an IRQ value. 
THE GOLD STAR INTERFACE 
The syntax for this CD-ROM interface is 


gscd=i obase 


THE MITSU MI STANDARD INTERFACE 
The syntax for this CD-ROM interface is 


mcd=i obase,[irq[,wait_value]] 


Thewait_value isused as an internal timeout value for people who are having problems with their drive and may or may 
not be implenented depending on acompiletime #define. TheM itsumi FX400 isan IDE/ATAPI CD-ROM player and 
does not use the mcd driver. 

THE MITSU MI XA/MULTISESSION INTERFACE (mcdx=) 
At present, this experimental driver has a setup function, but no parameters are implemented (as of 1.3.15). Thisis for the 
same hardware as previously described, but the driver has extended features. 

THE OPTICS STORAGE INTERFACE 
The syntax for this type of card is 


optcd=i obase 


THE PHILLIPS CM 206 INTERFACE 
The syntax for this type of card is 
cm206=[i obase][,irq] 


The driver assumes numbers between 3 and 11 areIRQ values and numbers between 0x300 and 0x370 arel/O ports, so you 
can specify one, or both numbers, in any orde’. It also accepts cm206=auto to gable autoprobing. 
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THE SANYO INTERFACE 
The syntax for this type of card is 


sjcd=iobase[,irq[,dma_channel ]] 


THE SOUNDBLASTER PRO INTERFACE 
The syntax for this type of card is 
sbpcd=i obase ,type 


type isone of the following (case-sensitive) strings: SoundBlaster, LaserMate, or sPEA. Thel/O baseisthat of theC D-ROM 
interface and not that of the sound portion of the card. 


ETHERNET DEVICES 


Different drivers use different parameters, but they all at least share having an IRQ, an I/O port basevalue and aname In 
its most generic form, it looks something like this: 


ether=irg,iobase[,param.1[,param2,...param 8]],name 
The first non-numeric argument is taken asthename Theparam_n values (if applicable) usually have different meanings for 


each different card or driver. Typical param_n values are used to specify things such as shared memory address, interface 
selection, DM A channd, and thelike. 


The most common use of this parameter is to force probing for a second ethercard because the default is to only probe for 
one This can be accomplished with asimple 


ether=0,0,eth1 
N ote that the values of @ for the IRQ and I/O basein the example tell the drivers to autoprobe 


The Ethernet H ow To has extensive documentation on using multiple cards and on the card-specific or driver-specific 
implenentation of theparam n values where used. Interested readers should refer to the section in that document on thar 
particular card. 


THE FLO PPY DISK DRIVER 
There are many floppy driver options, and they are all listed in README. fd iN linux/drivers/block. T hisinformation is taken 
directly from that file. 


floppy=mask, allowed drive mask 
Sets the bitmask of allowed drives to mask. By default, only units 0 and 1 of each floppy controller are allowed. T hisis done 
because certain non-standard hardware (ASU S PCI motherboards) mess up the keyboard when accessing units 2 or 3. This 
option is somewhat obsolete because of the cmos option. 

floppy=all drives 
Sets the bitmask of allowed drives to all drives. U se this if you havemore than two drives connected to a floppy controller. 


floppy=asus pci 
Sets the bitmask to allow only units 0 and 1 (the default). 


floppy=daring 


T dls the floppy driver that you havea well-behaved floppy controller. T his allows more efficient and smoother operation but 
may fail on certain controllers. This can speed up certain operations. 


floppy=0, daring 
T dls the floppy driver that your floppy controller should be used with caution. 
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floppy=one_fdc 
T alls the floppy driver that you have only one floppy controller (default). 


floppy=two_fdc OR floppy=address, two fdc 
T alls the floppy driver that you have two floppy controllers. The second floppy controller is assumed to be at address. If 
address is not given, @x370 is assumed. 


floppy=thinkpad 

Tells the floppy driver that you have a Thinkpad. Thinkpads use an inverted convention for the disk change line. 
floppy=0, thinkpad 

T alls the floppy driver that you don’t havea T hinkpad. 








floppy=drive, type, cmos 
Sets the cmos type of drive to type. Additionally, this drive is allowed in the bitmask. T his is useful if you have more than two 
floppy drives (only two can be described in the physical cmos), or if your BIOS uses non-standard cmos types. Setting the cmos 
to o for the first two drives (default) makes the floppy driver read the physical cmos for those drives. 


floppy=unexpected_interrupts 
Print a warning message when an unexpected interrupt is received (default behavior) 


floppy=no unexpected_interrupts OR floppy=L40SX 
Don’t print a message when an unexpected interrupt is recaved. This isneeded on IBM L40SxX laptops in certain video 
modes. (T here seems to be an interaction between video and floppy. T he unexpected interrupts only affect performance and 
can safdly be ignored.) 

THE SOUND DRIVER 


The sound driver can also accept boot args to override the compiled in values. Thisis not recommended because it is rather 
complex. It is described in the Readme.Linux filein linux/drivers/sound. It accepts a boot arg of the form 


sound=devicel[,device2[,device3...[,devicell]]] 

Each devicen value is of the format oxtaaal d and the bytes are used as follows: 

T— device type 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, aNd 7=SB16-MPU401 

aaa—I/O address in hex 

| — interrupt line in hex (10=a, 11=5, ... ) 

d—DMA channel 

As you can see, it gets pretty messy, and you are better off to compilein your own personal values as recommended. U sing a 
boot arg of sound=e disables the sound driver entirely. 


THE BUS MOUSE DRIVER (bmouse=) 


The busmouse driver only accepts one parameter, the hardware!RQ value to be used. 


AUTHORS 


Linus Torvalds (and many others) 


SEE ALSO 
klogd(8), 1ilo.conf(5), 1i10(8), mount(8), rdev(8) 


This man page was derived from the Boot Parameter HOWTO (version 1.0.1) written by Paul Gortmaker. M ore informa 
tion can be found in this (or amore recent) HOWTO. 


Linux 1.3.19, 15 August 1995 
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groftf me 


groff_me— troff macros for formatting papers. 


SYNOPSIS 
groff_me [ options ] file ... 
troff_me [ options ] file ... 
DESCRIPTION 


This manual page describes the GN U version of the_me macros, which is part of the groff document formatting system. 
This version can be used with both GNU troff and UNIX troff. This package of troff macro definitions provides a canned 
formatting facility for technical papers in various formats. 


The macro requests are defined as follows. M any troff requests are unsafe in conjunction with this package however, these 
requests can be used with impunity after the first . pp: 


.bp Begin new page 

.br Break output line here 

.Sp n Insert n spacing lines 

Is n Line spacing; n=1 single, n=2 double space 
na No alignment of right margin 

.ce n Center next n lines 

cul n Underline next n lines 


Output of the pic, eqn, refer, and tbl preprocessors is acceptable as input. 








FILES 
/usr/lib/groff/tmac/tmac.e 
SEE ALSO 
groff(1), gtroff(1), me Reference M anual, Eric P. Allman, Writing Papers with Groff Using_me 
REQUESTS 
This list is incomplete, see the _me Reference M anual for interesting details. 
Request Initial Value Caus Break Explanation 
.(C - Ys Begin centered block. 
.(d - No Begin delayed text. 
.(f - No Begin footnote 
(1 - YS Begin list. 
(q - YS Begin major quote. 
(XX - No Begin indexed item in index x. 
uz - No Begin floating keep. 
Je - YS End centered block. 
.)d - Ys End delayed text. 
yf - YS End footnote. 
il - Yes End list. 
.)q - YS End major quote 


continues 
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Request Initial Value Caus Break Explanation 

.)x - YS End index item. 

dz - YS End floating keep. 

t+ mH - No D efine paper section. 
m defines the part of the paper and can bec 
(chapter), a (appendix), P (preliminary, such as 
abstract, table of contents, and so on), B (bibliogra- 
phy), rc (chapters renumbered from page one each 
chapter), or ra (appendix renumbered from page 
one). 

te T - YS Begin chapter (or appendix and so on as set by .4). 
T isthe chapter title. 

1c YS Onecolumn format on a new page 

.2¢ Ys Two column format. Equation number isy. 

.EN - Ys Space after equation produced by eqn or neqn. 

EQ X y - Ys Precede equation; break out and add space. 
The optional argument x may be 1 to indent 
equation (default), L to left-adjust the equation, orc 
to center the equation. 

.GE - Ys End gremlin picture. 

.GS - YS Begin gremlin picture. 

.PE - Ys End pic picture. 

.PS - YS Begin pic picture. 

.TE - YS End table 

.TH - YS End heading section of table 

.TS x - Ys Begin table if x is, table has repeated heading. 

.b x No No Printx in boldface if no argument switch to 
boldface. 

.ba +n 0 YS Augments the base indent by n. 
This indent is used to set theindent on regular text 
(like paragraphs). 

.be No YS Begin new column. 

.bi x No No Print x in bold italics (no fill only). 

.bu - YS Begin bulleted paragraph. 

bx x No No Printx in abox (no fill only). 

ef ‘x 'y'z! “ No Set even footer tox y z. 

eh 'x'y'z! ae No Set even header to x y z. 

fo 'x'y'z! " No Set footer tox y z. 

.hx - No Suppress headers and footers on next page 

che 'x'y'z! " No Set header tox y z. 

Al - YS D raw ahorizontal line. 

ix No No Italicizex; if x is missing, italic text follows. 

sip x y No YS Start indented paragraph with hanging tag x. 


Indentation isy ens (default is 5). 
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Request Initial Value Caus Break Explanation 
lp YS Ys Start left-blocked paragraph. 
.np 1 YS Start numbered paragraph. 
of 'x'y'z! un No Se odd footer tox y z. 
coh 'x'y'z! we No Set odd header tox y z. 
.pd - Ys Print delayed text. 
“pp No YS Begin paragraph. First line indented. 
Als YS No Roman text follows. 
.re - No Reset tabs to default values. 
sh n x - Ys Section head follows; font is automatically bold. n is 
level of section. x is title of section. 
«sk No No Leave the next page blank. O nly one page is 
remembered ahead. 
.sm Xx - No Se x in asmaller point size 
.8Z 4n 10p No Augment the point size by n points. 
.tp No YS Begin title page. 
LUX - No Underline argument (even in troff) (nofill only). 
.uh - YS Like .sh but unnumbered. 
.Xp x - No Print index x. 
Groff Verson 1.09, 6 August 1992 
groff_mm 
groff_mm— groff mm Macros. 
SYNOPSIS 
groff_mgm [ options... ] [files... ] 
DESCRIPTION 


The groff mm macros are intended to be compatible with the ows mm macros with the following limitations: 
No letter macros are implemented (yet). 

N o Bell Labs localisms are implemented. 

The macros ok and pm are not implemented. 

groff mm does not support cut marks. 


mgm isintended to be international. Therefore, it is possible to write short national macro-files that change all English text to 
the preferred language. Use mgmse as an example. 


groff mm has several extensions: 


1C [1] Begin one column processing. A 1 as argument disables the page break. 

APP name text Begin an appendix with thename name. Automatic naming occurs if nameis"". The 
appendixes starts with A if auto is used. A new page is ejected, and a header is also 
produced if thenumber variable aph is non-zero. T hisis the default. T he appendix 
always appear in thelist of contents with the correct page number. The name 
APPENDIX Can be changed by setting the string App to the desired text. 
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APPSK name pages text 


B1 
B2 
BVL 


COVER [arg] 


COVEND 


GETHN refname [varname ] 
GETPN refname [varname ] 


GETR ref name 


GETST refname [varname ] 

INITR filename 

MC column-size [column-separation] 
MT [arg [addressee ]] 


MOVE y-pos [x-pos[line-length]] 


Same as .ApP, but the page number is incremented with pages. T his is used 
when diagrams or other non-formatted documents are included as appen- 
dixes. 

Begin box (as thems macro) D raws abox around thetext. 

End box. Finish the box. 

Start of broken variable-item list. Like vi but text begins always at the next 
line 

cover begins a coversheet definition. It is important that .cover appears 
before any normal text. .cover usesarg to build the filavame /usr/1ib/groff/ 
tmac/mm/arg.cov. Therefore, it is possible to create unlimited types of 
coversheets. ms. cov is supposed to look like the ms coversheet. .cover requires 
a .COVEND at the end of the cover definition. Always use this order of the cover 
macros: 

.COVER 

.TL 

LAF 

.AU 

.AT 

.AS 

LAE 

.COVEND 

H owever, only .TL and .au are required. 

This finishes the cover description and prints the cover page It is defined in 
the cover file. 

Includes the header number where the corresponding SETR ref name WaS 
placed. Will bex.x.x. in pass 1. See rnrTR. If varname iS used, GETHN sets the 
string variablevarname to the header number. 

Includes the page number where the corresponding SETR ref name was placed. 
Will be 9999 in pass 1. See rnrTR. If varname iS used, GETPN Sets the string 
variablevarname to the pagenumbe. 


Combines GETHN and ceTen with the text ‘chapter' and ', page'. Thestring 
Qrf contains the text for reference: .ds Qrf See chapter \\*[Qrfh], page 
\\*[Qrfp J. Qrf may be changed to support other languages. Strings qr fh and 
Qrfp are set by GeTR and contain the page and header number. 

Includes the string saved with the second argument to .setr. Will be dummy 
string in pass 1. If varname is used, GeTsT sets the string variable varname to the 
saved string. See INITR. 

Initialize the reference macros. References will be written to filename. tmp 
and filename .qrf. Requires two passes with groff. The first looks for 
references and the second includes them. 1n1TR can be used several times, but 
it isonly the first occurrence of 1nrTR that is active. See also SETR, GETPN, and 
GETHN. 

Begin multiple columns. Return to normal with 1c. 

Memorandum type. Thearg ispart of afilenamein /usr/1ib/groff/tmac/mm/ 
«mT. Memorandum type @ through 5 are supported, including string. 
addressee just sets a variable, used in the AT&T macros. 

M ove to aposition, page offset set to x- pos. Ifline-length isnot given, the 
difference between the current and new page offset is used. U se PaForm 
without arguments to return to normal. 











MULB cwl spacel[cw2 space2 [cw3 ...]] 


MULN 
MULE 


PGFORM [linelength[pagelength[pageoffset [1]]]] 
linelength, pagelength and/Or pageoffset. 


PGNH 


SETR refname [string] 


TAB 


VERBON [flag [pointsize[font ]]] 


VERBOFF 
N ew variables in mgm: 


App 
Aph 


groff_mm 


Begin aspecial multi-column mode. Every column's width must 
be specified. Also, the space between the columns must be 
specified. The last column does not need any space definition. 
MULB starts a diversion and mute ends the diversion and prints the 
columns. The unit for width and space isn, but mute accepts all 
normal unit specifications such asc and i. muLB operates in a 
separate environment. 

Begin the next column. T hisis the only way to switch columns. 
End the multi-column modeand print the columns. 

This macro can be used for special formatting, such as PaForM 
letterheads. Sets can be used without arguments to reset 
everything after a move. A line break is done unless the fourth 
argument is given. This can be used to avoid the page number 
on the first page while setting new width and length. 

No header is printed on the next page. Used to get rid of the 
header in letters or other special texts. T his macro must be used 
before any text to inhibit the page header on the first page 
Remember the current header and pagenumber asr ef name. Saves 
string if string iSdefined. string isretrieved with .ceTsT. See 
INITR. 

Reset tabs to every 5n. Usually used to reset any previous tab 
positions. 

Begin verbatim output using Courier font. U sually for printing 
programs. All characters have equal width. The point size can be 
changed with the second argument. By specifying the font 
argument, it is possible to use another font instead of C ourier. 
flag controls several special features. It contains the sum of all 
wanted features: 





Value D excription 

1 Disable the escape character (n). T his is usually 
turned on during verbose output. 

2 Add an empty line before the verbose text. 

4 Add an empty line after the verbose text. 

8 Print the verbose text with numbered lines. T his 


adds four digit-sized spaces in the beginning of 
each line. Finer control is available with the 
string-variable verbnm. It contains all arguments 
to the troff-command .nnm, usually 1. 


16 Indent the verbose text with five ns. This is 
controlled by the number-variable verbin (in 
units). 





End verbatim output. 


A string containing the word APPENDIX. 


Print an appendix page for every new appendix if this number 
variable is nonzero. N o output will occur if Aph iszero, but there 
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will always be an appendix entry in the list of contents. 


Hps N umber variable with the heading pre-space leva. If the heading 
level is less than or equal to Hps, then two lines precede the section 
heading instead of one. D efault is first level only. The real amount 

















of linesis controlled by the variables Hps1 and Hps2. 
Hps1 This is the number of lines preceding .4 when the heading level is 
greater than Hps. Value isin units, usually o.5v. 
Hps2 Thisis the number of lines preceding .4 when the heading level is 
less than or equal to Hps. Valueisin units, usually tv. 
Lifg String containing figure 
Litb String containing table 
Liex String containing exhibit. 
Liec String containing equation. 
Licon String containing contents. 
Lsp Thesize of an empty line. U sually o.5v, but itis 1v if n isset 
(.nroff). 
MO1 - MO12 Strings containing J anuary to D ecember. 
art String containing "See chapter \\*[Qrfh], page \\n[Qrfp].". 
Pgps Controls whether header and footer point size should follow the 
current setting or just change when the header and footer is 
defined. 
Value D excription 
0 Point size will only change to the current setting 
when .PH, .PF, .OH, .EH, .OF, OF .0E is executed. 
1 Point size will change after every .s. Thisis the 
default. 
Sectf Flag controlling section figures. A nonzero value enables this. See 
also regista N. 
Sectp Flag controlling section page numbers. A nonzero value enables 
this. See also register N. 
.mgm Always 1. 


A file called locale or lang_locale iS read after the initiation of the global variables. | t is therefore possible to localize the 
macros with a company name and so on. 


The following standard macros are implemented: 


2c Begin two column processing. 

AE Abstract end. 

AF [name of firm] Author's firm. 

AL [type[text-indent [1]]]] Start autoincrement list. 

AS [arg [indent ]] Abstract start. Indent is specified in ens, but scaling is allowed. 
AST [title] Abstract title D efault is ‘ABSTRACT’. 

AT titlel [title2 ...] Author's title 


AU name [initials [loc [dept 
[ext [room [arg [arg 
[arg}111]1]] Author information. 


B [bold-text [prev-font-text [...]]] Begin boldface. No limit on the number of arguments. 


BE 
BI[ 
BL 
BR 
BS 
DE 
DF 
DL 
Ds 


EC 


EF 
EH 
EN 
EQ 
EX 


FD 
FE 
FG 


FS 

| 
iC 
M 
U 
Xx 
Y 
Z 





H 
H 
H 
H 
H 
H 
H 
I 


IB 


IR 


LB 


LC 
LE 
LI 
ML 
MT 


old-text [italic-text [bold-text [...]]] 
text-indent [1]] 
bold-text [roman-text [bold-text [...]]] 


ormat [fill [rindent ]]] 
text-indent [1]] 
format [fill [rindent ]]] 





title [override[flag [refname]]]] 


arg] 
arg] 


label ] 
title [override[flag [refname]]]] 


arg [1]] 





title [override[flag [refname]]]] 


evel [heading-text [heading-suffix]] 
[hyphenation-character ] 

[argl [arg2[... [arg7]]]] 
heading-text 








dlevel rlevel heading-text 
dlevel rlevel heading-text 
dlevel rlevel heading-text 
italic-text. 
italic-text 
italic-text 


ext-indentmark-indent 


list level ] 


mark [1]] 


mark [text-indent ] 





arg [addressee]] 
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End bottom block. 


Bold italic. N o limit on the number of arguments. 
Start bullet list. 

Bold roman. N o limit on thenumber of arguments. 
Bottom block start. 

Display end. 

Begin floating display (no nesting allowed). 

D ash list start. 


Static display start. Can now have unlimited nesting. Also, right- 
adjusted text and block may be used (r or rB as format). 


Equation title If refname isused, then the equation number is 
saved with .setr and can be retrieved with .GETST ref name. 


Even page footer. 
Even page header. 
Equation end. 
Equation start. 


Exhibit title. If ref name is used, then the exhibit number is saved 
with .seTr and can be retrieved with .GETST ref name. 


Footnote default format. 
Footnoteend. 


Figure title If refname isused, then the figure number is saved 
with .seTr and can be retrieved with .GETST ref name. 


Footnote start. Footnotesin displays is now possible. 

N umbered heading. 

Set hyphenation character. 

H eading mark style 

Unnumbered heade.. 

User-defined heading exit. C alled just before printing the header. 
User-defined heading exit. Called just before printing the header. 
User-defined heading exit. Called just after printing the header. 


prev-font-text 
italic-text [...]] Italic. 





bold-text 
italic-text [...]] Italic bold. 
roman-text 
italic-text [...]] Italic roman. 





pad type [mark 
Ll-space [LB-space]]] List begin macro. 
List status clear. 

List end. 

List item. 

M arked list start. 

M emorandum type. See above note about mr. 














Ea 


ND 
OF 
OH 
oP 
P 
PE 
PF 
PH 
PS 
PX 
R 
RB 


RD 
RF 
RI 


RL 
RP 
RS 
S[ 


SA 
SK 
SM 
SP 
TB 


TC 


TE 
TH 
TL 
™ 


TP 


TS 
TX 
TY 
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new- date 
arg] 
arg] 


ype] 


arg] 
arg] 





roman-text [bold-text 


prompt [diversion [string]]] 


roman-text 


text-indent [1]] 


arg [arg]] 
string- name ] 





size [spacing]] 


arg] 

pages ] 

stringl[string2 [string3]] 
lines] 


title [override[flag [refname]]]] 





slevel [spacing 


[N] 


[numl [num2 [...]]] 


[H] 


N ew date 

O dd page footer. 

Odd page header. 

Skip to odd page. 
Begin new paragraph. 
Picture end. 

Page footer. 

Page heade.. 

Picture start (from pic). 
Page header user-defined exit. 
Roman. 


[roman-text [...]]] Roman-bold. 
Read to diversion and/or string. 
Reference end. 


[italic-text 
[roman-text [...]]] 
Reference list start. 
Produce reference page. 
Reference start. 


Sé& point size and vertical spacing. If any argument equals p, then the 
previous value is used. A c means current value, and p means default 
value. If + or - isused before the value, an increment or decrement of 
the current value is done. 


Se adjustment. 

Skip pages. 

M ake a string smaller. 

Space vertically. |i nes can haveany scaling factor, such as 3: or sv. 


Tabletitle If refname is used, then thetable number is saved with 
.SETR and can be retrieved with .GETST ref name. 


Roman italic. 


[tlevel [tab [hl [h2 

[h3 [h4 [h5]11I1110) 

Table of contents. All texts can be redefined. new string variables 
Lifg, Litb, Liex, Liec, aNd Licon contain "Figure", "TABLE", "Exhibit", 
"Equation", and "CONTENTS". T hese can be redefined to other 
languages. 

Table end. 

T able header. 

Begin title of memorandum. 

Technica memorandum numbers used in .wt. Unlimited number of 
arguments may be given. 

Top of page user-defined macro. N ote that header and footer is 
printed in a separate environment. Line length is preserved. 

T able start. 

User-defined table of contents exit. 

User-defined table of contents exit (no "ConTENTS"). 
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VL [text-indent [mark-indent [1]]] Variableitem list start. 
VM [top [bottom]] Vertical margin. 
WC [format ] Footnote and display width control. 


Strings used in mgm: 


EM Em dash string. 

HF Font list for headings, usually "2 2 2 2 2 2 2". Nonnumeric font 
names may also be used. 

HP Point size list for headings. Usually "a @ @ @ @ @ a", whichis the 
saMe aS "10 10 10 10 10 10 10". 

Lf Contains "LIsT OF FIGURES". 

Lt Contains "LIsT OF TABLES". 

Lx Contains "LIsT OF EXHIBITS". 

Le Contains "L1sT OF EQUATIONS". 

Rp Contains "REFERENCES". 

Tm Contains \ (tm, trademark. 


N umber variables used in mgm: 


C1=2 Contents level [0:7]; contents saved if heading levd <=c1. 
Cp=0 Eject page between LIsT OF xxxx if Cp == 0. 
D=0 D ebug flag, values greater than @ produce varying degree of debug. A 


value of 1 gives information about the progress of formatting. 





De=0 Eject after floating display is output [0:1]. 

Df=5 Floating keep output [0:5]. 

Ds=1 Space before and after display if =1 [0:1]. 

Ej=0 Eject page. 

Eq=0 Equation label adjust exeft, 1=right. 

Fs=1 Footnote spacing. 

H1 - H7 H eading counters. 

Hb=2 H eading break level [0:7]. 

Hc=0 H eading centering level [0:7]. 

Hi=4 H eading temporary indent [0:2]. @ isno indent, left margin. 1 is 


indent to right, like .p 1. 2 isindent to line up with text part of 
preceding heading. 








Hs=2 H eading space level [0:7] 

Ht=0 H eading numbering type a ismultiple(1.1.1...). 1 issingle. 

Hu=2 Unnumbered heading level. 

Hy=1 H yphenation in body. @ isno hyphenation. 1 ishyphenation 14 on. 

Lf=1, Lt=1, Lx=1, Le=0 Enables (1) or disables (a) the printing of a list of figures, list of tables, 
list of exhibits, and list of equations. 

Li=6 List indent, used by .AL. 

Ls=99 List space if current list level is greater than Ls, then no spacing 
occurs around lists. 

N=0 N umberving style [0:5]: 


@ =(D efault) Normal header for all pages. 
1 =H eade replaces footer on first page; header is enpty. 
2 =Page header is removed on the first page. 
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Pi=5 
Ps=1 
Pt=0 


$i=5 


AUTHOR 


3 = Section page numbering enabled. 

4 =Page header is removed on the first page. 

5 == Section page and section figure numbering enabled. See also the 
number register sectf and Sectp. 

N umbered paragraphs. @ isnot numbered. 1 is numbered in first-level 
headings. 

Format of figure, table, exhibit, and equation titles. Qis". ".lis"-". 


Current page number, usually the same as % unless section-page 
numbering is enabled. 

Paragraph indent. 

Paragraph spacing. 

Paragraph type. o is left-justified. 1 isindented .p. 2 isindented .p 
except after .H, .DE, OF .LE. 

Display indent. 


Jorgen H agg, Lund Institute of Technology, Sweden (jh@efd.ith.se). 


FILES 


/usr/lib/groff/tmac/tmac. gm 
/usr/lib/groff/tmac/mm/*.cov 
/usr/lib/groff/tmac/mm/*.MT 
/usr/lib/groff/tmac/mm/locale 


SEE ALSO 


groff(1), gtroft(1), gtbi(1), gpic(1), geqn(1), mm 


groff ms 


groff_ms— groff ms Macros. 


SYNOPSIS 


groff_mgs [ options... ] [files... ] 


DESCRIPTION 


(7), mgmse(7) 


Groff Verson 1.09, 14 February 1994 


This manual page describes the GN U version of thems macros, which is part of the groff document formatting system. The 
groff ms Macros are intended to be compatible with the documented behavior of the 4.3 BSD UNIX ms macros, subject to 


the following limitations: 


Theinternals of groff ms are not similar to the internals of UN IX ms, so documents that depend upon implementation 


details of UNIX ms might not work with groff ms. 
There is no support for typewriter-like devices. 


Berkeley localisms, in particular the tu and ct macros, are not implemented. 


groff ms does not provide cut marks. 


M ultiple line spacing isnot allowed. (U se alarger vertical spacing instead.) 


groff ms does not work in compatibility mode (such as with the -c option). 


groff_ms [2 | 


The groff ms macros use many features of GN U troft and therefore cannot be used with any other troff. 


Theerror-handling policy of groff ms isto detect and report errors, rather than silently ignore then. 


Bal Labslocalisms are not implanented in eithe the BSD ms macrosor in the groff ms macros. 


SomeU NIX ms documentation says that the cw and ew number registers can be used to control the column width and gutter 
width. This is not the case. T hese number registers are not used in groff ms. 


M acrosthat cause a reset set the indent. M acros that change the indent do not increment or decrement the indent, but rather 
set it absolutely. This can cause problens for documents that define additional macros of thar own. T hesolution isto not 
use the in request but instead to use the rs and rE macros. 


Thenumber register es is set to 1 by the groff ms macros but is not used by the UNIX ms macros. It is intended that 
documents that need to determine whether they are being formatted with UNIX ms or groff ms use this number register. 


Footnotes are implemented so that they can safely be used within keeps and displays. Automatically numbered footnotes 
within floating keeps are not recommended. It is safe to have another \** between a \** and the corresponding .Fs; itis 
required only that each .Fs occur after the corresponding \** and that the occurrences of .Fs are in the same order as the 
corresponding occurrences of \**. 


The strings \*{ and \*} can be used to begin and end a superscript. 


SomeU NIX V 10 ms features are implemented. The, 1, and 81 macros can havean optional third argument that is printed 
in thecurrent font beforethe first argument. T here is a macro cw like B that changes to a constant-width font. 


The following strings can be redefined to adapt the grott ms macros to languages other than English: 





String Default Value 
REFERENCES References 
ABSTRACT ABSTRACT 

TOC Table of Contents 
MONTH1 January 
MONTH2 February 
MONTHS March 

MONTH4 April 

MONTHS May 

MONTH6 June 

MONTH7 July 

MONTH8 August 
MONTH9 September 
MONTH10 October 
MONTH11 November 
MONTH12 December 





The font family is reset from the string Fam; at initialization if this string is undefined, it is set to the current font family. The 
point size vertical spacing, and inter-paragraph spacing for footnotes are taken from the number registers Fs, Fvs, and FPp; 
at initialization, these are set to \n(PS-2, \n[FPS]+2, and \n(PD/2; howeve,, if any of these registers was defined before 
initialization, it isnot set. The hyphenation flags (as set by the .hy request) are set from the ny register; if this was not defined 
at initialization, it isset to 14. 


Right-aligned displays are available with .ps R and .rb. 


The following conventions are used for names of macros, strings, and number registers. External names available to 
documents that use the groff ms macroscontain only uppercase letters and digits. Internally, the macros are divided into 
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modules. N ames used only within one module are of the form modu! e *name. N ames used outside the module in which they 
are defined are of the form module @name. N ames associated with a particular environment are of the form environment :name; 
these are used only within the par module, and name does not havea module prefix. Constructed names used to implement 
arrays are of the form array tindex. Thus, the groff ms macros reserve the following names: 

N ames containing * 

N ames containing @ 

N ames containing : 

N ames containing only uppercase letters and digits 


FILES 


/usr/lib/groff/tmac/tmac.gs 


SEE ALSO 


groff(1), gtroff(1), gtb1(1), gpic(1), geqn(1), ms(7) 
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hier 
hier— D escription of the filesystem hierarchy. 
DESCRIPTION 


A typical Linux system has, among others, the following directories: 


/ Thisis the root directory. T hisis where the whole tree starts. 

/bin This directory contains executable programs that are needed in single-user mode and to 
bring the systen up or repair it. 

/boot Contains static files for the boot loader. This directory only holds the files that are 


needed during the boot process. The map installer and configuration files should go to / 
sbin and /etc. 





/dev Special or device files that refer to physical devices. See mknod(1). 

/dos If both MS-DOS and Linux arerun on one computer, this is a typical place to mount a 
DOS filesystem. 

/etc Contains configuration files that are local to the machine. Some larger software 


packages, such as X11, can have their own subdirectories below /etc. Site-wide 
configuration files may be placed hereor in /usr/etc. N evertheless, programs should 
always look for these filesin /etc and you may have links for these files to /usr/etc. 


/etc/skel W hen anew user account is created, files from this directory are usually copied into the 
user’s home directory. 

/etc/X11 Configuration files for the X11 window systen. 

/home On machines with home directories for users, these are usually beneath this directory, 
directly or not. The structure of this directory depends on local administration 
decisions. 

/lib This directory should hold those shared libraries that are necessary to boot the systen 
and to run the commands in the root filesystem. 

/mnt This is amount point for temporarily mounted filesystems. 

/proc Thisis amount point for the proc filesystem, which provides information about 


running processes and the kernal. T his pseudo-filesystem is described in more detail in 
proc(5), 


/sbin 


/tmp 


/usr 


/usr/X11R6 
/usr/X11R6/bin 


/usr/X11R6/lib 
/usr/X11R6/1ib/X11 


/usr/X11R6/include/X11 


/usr/bin 


/usr/bin/X11 


/usr/dict 


/usr/etc 


/usr/include 


/usr/include/X11 


/usr/include/asm 


/usr/include/ linux 





/usr/include/g++ 


/usr/lib 


/usr/1ib/X11 


/usr/lib/gcc-lib 
/usr/lib/groff 
/usr/lib/uucp 
/usr/lib/zoneinfo 
/usr/loca 
/usr/local/bin 
/usr/local/doc 
/usr/local/etc 
/usr/local/lib 
/usr/local/info 


/usr/local/man 








/usr/local/sbin 


hier 1237 


Like /bin, this directory holds commands needed to boot the system but usually not 
executed by normal users. 


This directory contains temporary files that may be ddeted with no notice, such asbya 
regular job or at system bootup. 


This directory is usually mounted from a separate partition. It should hold only 
sharable, read-only data so that it can be mounted by various machines running Linux. 


TheX window systen, version 11, release 6. 


Binaries that belong to the X window system; often, there is a symbolic link from the 
moretraditional /usr/bin/x11 to hee 


D ata files associated with the X window system. 


T hese contain miscellaneous files needed to run X; Often, thereis a symbolic link from 
/usr/1ib/x11 to this directory. 


Contains include files needed for compiling programs using the X 11 window system. 
Often, there is asymbolic link from /usr/include/x11 to this directory. 


This is the primary directory for executable programs. M ost programs executed by 
normal users that are not needed for booting or for repairing the system and that are not 
installed locally should be placed in this directory. 


This is the traditional place to look for X11 executables; on Linux, it usually isa 
symbolic link to /usr/x11R6/bin. 


This directory holds files containing word lists for spell-checkers. 


Site wide configuration files to be shared between several machines may be stored in this 
directory. H owever, commands should always reference those files using the /etc 
directory. Links from files in /etc should point to the appropriate files in /usr/etc. 


Include files for theC compiler. 


Include files for theC compiler and the X window system. T his is usually a symbolic 
link to /usr/X11R6/include/xX11. 


Include files that declare some assembler functions. T his should be a symbolic link to / 
usr/src/linux/include/asm 


This contains information that may change from system release to system rd ease and 
should be a symbolic link to /usr/src/linux/include/1linux to get at operating-system- 
specific information. 


Include files to use with the GNU C++ compiler. 


O bject libraries, including dynamic libraries, plus some executables that usually are not 
invoked directly. M ore complicated programs may have whole subdirectories there. 


The usual place for data files associated with X programs and configuration files for the 
X system itsdf. On Linux, it usually isasymbolic link to /usr/x11R6/1ib/X11. 


Contains executables and include filesfor theG NU C compiler, gcc(1). 
les for the GNU grotf document formatting system. 

Files for uucp(1). 

Files for time zone information. 

This is where programs that are local to thesite typically go. 
Binaries for programs local to the site go there. 
Li 
C 





nm 


ocal documentation. 

onfiguration files associated with locally installed programs go there. 
les associated with locally installed programs go there. 

Info pages associated with locally installed programs go there 

M an pages associated with locally installed programs go there 

Locally installed programs for system administration. 





nm 
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/usr/local/src 
/usr/man 


/usr/man/cat[1-9] 
/usr/man/|ocale/man[1-9] 
/usr/sbin 


/usr/src 
/usr/src/linux 
/usr/tmp 

/var 

/var/adm 


/var/lock 


/var/log 
/var/preserve 


/var/run 


/var/spoo 
/var/spool/at 
/var/spool/cron 
/var/spool/1pd 
/var/spool/mail 
/var/spool/smail 


/var/spool/news 





/var/spool/uucp 
/var/tmp 


CONFORMS TO 


Source code for locally installed software. 
M an pages go in thereinto ther subdirectories. 


T hese directories contain preformatted manual pages according to their man page 
section. 


T hese directories contain manual pages that are in source code form. Systems that use a 
unique language and code set for all manual pages may omit the! ocale substring. 


This directory contains program binaries for system administration that are not essential 
for the boot process, for mounting /usr, or for system repair. 


Source files for different parts of the system. 

This contains the sources for the kernel of the operating system itself. 

An alternative place to store temporary files; This should bea link to /var/tmp. 
This directory contains files that may change in size, such as spool and log files. 
This directory is superseded by /var/1og and should be a symbolic link to /var/1og. 


Lock files are placed in this directory. The naming convention for device lock files is 
LCK..device wheredevice isthe device's namein the filesystem. T he format used is that 
of HDU UUCP lock files— that is, lock files contain a PID asa10-byte ASCII decimal 
number, followed by a newline character. 


M iscdlaneous log files. 
This is where vi(1) saves edit sessions so they can be restored later. 


Runtime variable files, such as files holding process identifiers (PID s) and logged user 
information (utmp). Files in this directory are usually cleared when the system boots. 


Spooled (or queued) files for various programs. 

Spooled jobsfor at(1). 

Spooled jobs for cron(1). 

Spooled files for printing. 

Users’ mailboxes. 

Spooled files for the smai1(1) mail ddivery program. 

Spool directory for the news subsystem. 

Spooled files for uucp(1). 

Like /tmp, this directory holds temporary files stored for an unspecified duration. 








The Linux filesystem standard, release 1.2. 


BUGS 


This list is not exhaustive, different systems may be configured differently. 


SEE ALSO 


find(1), 1n(1), mount(1), proc(5), The Linux Filesystem Standard 


hostname 


Linux, 10 February 1996 


hostname— H ostname resolution description. 


hostname 
DESCRIPTION 


H ostnames are domains. A domain isa hierarchical, dot-separated list of subdomains. For example, the machine monet in the 
Berkeley Subdomain of the Epu subdomain of the Internet D omain N ame System is represented aS monet.Berkeley.EDU (with 
no trailing dot). 


H ostnames are often used with network client and server programs, which must generally translate the name to an address 
for use, (This task is usually performed by the library routine gethostbyname(3).) The default method for resolving hostnames 
by the Internet name resolver is to follow RFC 1535's security recommendations. Actions can be taken by the administrator 
to override these recommendations and to have the resolver behave the same as earlier, non-RFC 1535 resolvers. 


The default method (using RFC 1535 guidelines) follows. 


If the name conssts of a single component (that is, contains no dot) and if the environment variable HosTALtases is set to the 
nameof afile, that file is searched for a string matching the input hostname T hefile should consist of lines made up of two 
strings separated by whitespace the first of which is the hostname alias and the second of which is the complete hostname to 
be substituted for that alias. If a case insensitive match is found between the hostname to be resolved and the first field of a 
linein the file, the substituted name is looked up with no further processing. 


If there is at least one dot in thename then the nameisfirst tried asis. The number of dots to cause this action is 
configurable by setting the threshold using the ndots option in /etc/resolv.conf (default is 1). If the name ends with a dot, 
the trailing dot is removed, and the renaining name is looked up (regardless of the setting of the ndots option) and no 
further processing is done 

If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until amatch is 
found. If neither the search option in the /etc/resolv.cont file or the LocALDOMAIN environment variable is used, then the 
search list of domains contains only the full domain specified by the domain option (in /etc/resolv.conf) or the domain 
used in the local hostname (see hostname(1) and resolver(5)). For example, if the domain option is set to cS.Berkeley.EDU, 
then only cs.Berkeley.eDu isin the search list and is the only domain appended to the partial hostname For example, a 
setting of lithium makes lithium.cS.Berkeley.eDu the only nameto be tried using the search list. 

If the search option isused in /etc/resolv.conf or the environment variable, LocaLDomAIN is set by the user, then the search 
list includes what is set by these methods. For example if the search option contained cs.Berkeley.EDU CChem.Berkeley.EDU 
Berkeley.EDU, then the partial hostname (such as 1ithium) is tried with each domain name appended (in the same order 
specified). The resulting hostnames that are tried include 

lithium.CS.Berkeley.EDU 

lithium.CChem.Berkeley.EDU 

lithium.Berkeley.EDU 

The environment variable LocaLDomaIn overrides the search and domain options, and if both search and domain options are 
present in the resolver configuration file then only the last one listed is used (see resolver(5)). 

If the name was not previously tried “asis” (that is, it fell bdow the ndots threshold or did not contain a dot), then thename 
as originally provided is attempted. 


SEE ALSO 


gethostbyname(3), resolver(5), mailaddr(7), named(8) 
16 February 1994 


180 8859 1 
iso_8859 1—ThelSO 8859-1 character set encoded in octal, decimal, and hexadecimal. 


DESCRIPTION 


ThelSO 8859 standard includes several 8-bit extensions to the ASCII character set (also known as!SO 646-IRV). Especially 
important is!SO 8859-1, the Latin Alphabet N 0. 1, which has become widely implemented and may already be seen as the 
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de facto standard ASCII replacenent. ISO 8859-1 supports the following languages: Afrikaans, Basque, Catalan, D anish, 

Dutch, English, Faeroes, Finnish, French, Galician, German, Icdandic, Irish, Italian, N orwegian, Portuguese, Scottish, 

Spanish, and Swedish. N otethat the|SO 8859-1 characters are also the first 256 characters of ISO 10646 (Unicode). 
ISO 8859 ALPHABETS 

The full set of ISO 8859 alphabets includes 


ISO 8859-1 W est European languages (L atin-1) 

ISO 8859-2 East European languages (Latin-2) 

ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) 
ISO 8859-4 Scandinavian/Baltic languages (Latin-4) 

ISO 8859-5 Latin/C yrillic 

ISO 8859-6 Latin/Arabic 

ISO 8859-7 Latin/G reek 

ISO 8859-8 Latin/H ebrew 

ISO 8859-9 Latin-1 modification for T urkish (Latin-5) 

ISO 8859-10 Lappish/N ordic/Eskimo languages (Latin-6) 


ISO 8859-1 CHARACTERS 
T he following table displays the characters in ISO 8859 Latin-1, which are printable and unlisted in the ascii(7) manual 





page. 
Oct Dec HEX Char Description 
240 160 AO N o-break space 
241 161 Al i Inverted exclamation mark 
242 162 A2 ¢ Cent sign 
243 163 A3 £ Pound sign 
244 164 A4 $ Currency sign 
245 165 A5 ¥ Yen sign 
246 166 A6 i Broken bar 
247 167 A7 § Section sign 
250 168 A8 ‘ D iaeresis 
251 169 AQ © Copyright sign 
252 170 AA = Feminine ordinal indicator 
253 171 AB << Left-pointing double angle quotation 
mark 
254 172 AC a Not sign 
255 173 AD - Soft hyphen 
256 174 AE ® Registered sign 
257 175 AF : M acron 
260 176 BO a D egree sign 
261 177 Bl + Plus-minus sign 
262 178 B2 2 Superscript two 


263 179 B3 3 Superscript three 


i 8859 1 








Oct Dec HEX Char Description 

264 180 B4 Acute accent 

265 181 B5 Micro sign 

266 182 Bo I Pilcrow sign 

267 183 B7 : M iddle dot 

270 184 B8 ¢ Cadilla 

271 185 B9 t Superscript one 

272 186 BA 2 M asculine ordinal indicator 

273 187 BB >> Right-pointing double angle 
quotation mark 

274 188 BC 1/4 Vulgar fraction one quarter 

275 189 BD 1/2 Vulgar fraction one half 

276 190 BE 3/4 Vulgar fraction three quarters 

277 191 BF é Inverted question mark 

300 192 co A Latin capital lette A with grave 

301 193 C1 A Latin capital letter A with acute 

302 194 C2 A Latin capital letter A with circumflex 

303 195 C3 A Latin capital letter A with tilde 

304 196 C4 A Latin capital letter A with diaeresis 

305 197 C5 A Latin capital letter: A with ring above 

306 198 C6 E Latin capital ligature AE 

307 199 C7 ¢ Latin capital letter’ C with cedilla 

310 200 C8 E Latin capital letter E with grave 

311 201 cg E Latin capital letter E with acute 

312 202 CA E Latin capital letter E with circumflex 

313 203 CB E Latin capital letter E with diaeresis 

314 204 CC i Latin capital lette | with grave 

315 205 CD i Latin capital lette | with acute 

316 206 CE i Latin capital lette | with circumflex 

317 207 CF i Latin capital letter | with diaeresis 

320 208 DO D Latin capital letter eth 

321 209 D1 N Latin capital letter N with tilde 

322 210 D2 O Latin capital lette O with grave 

323 211 D3 0 Latin capital letter O with acute 

324 212 D4 6 Latin capital lette O with circumflex 

325 213 D5 ©) Latin capital lette' O with tilde 

326 214 D6 6 Latin capital letter O with diaeresis 

327 215 D7 x M ultiplication sign 

330 216 D8 i) Latin capital lette’ O with stroke 

331 217 D9 U Latin capital lette U with grave 

332 218 DA U Latin capital letter U with acute 

333 219 DB U Latin capital letter U with circumflex 

















continues 
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Oct Dec HEX Char Description 

334 220 DC U Latin capital letter U with diaeresis 

335 221 DD Y Latin capital letter: Y with acute 

336 222 DE p Latin capital letter thorn 

337 223 DF R Latin small letter sharp s 

340 224 E0 a Latin small letter a with grave 

341 225 El a Latin small letter a with acute 

342 226 E2 a Latin small letter a with circumflex 

343 227 E3 a Latin small letter a with tilde 

344 228 E4 a Latin small letter a with diaeresis 

345 229 E5 a Latin small letter a with ring above 

346 230 E6 we Latin small ligature ae 

347 231 E7 ¢ Latin small letter c with cedilla 

350 232 E8 é Latin small letter e with grave 

351 233 E9 é Latin small letter e with acute 

352 234 EA é Latin small letter e with circumflex 

353 235 EB é Latin small letter e with diaeresis 

354 236 EC 1 Latin small letter i with grave 

355 237 ED i Latin small letter i with acute 

356 238 EE i Latin small letter i with circumflex 

357 239 EF i Latin small letter i with diaeresis 

360 240 FO te) Latin small letter eth 

361 241 Fl fl Latin small letter n with tilde 

362 242 F2 0 Latin small letter o with grave 

363 243 F3 6 Latin small letter o with acute 

364 244 F4 6 Latin small letter o with circumflex 

365 245 F5 6 Latin small letter o with tilde 

366 246 F6 6 Latin small letter o with diaeresis 

367 247 F7 - Division sign 

370 248 F8 vy) Latin small letter o with stroke 

371 249 F9 U Latin small letter u with grave 

372 250 FA U Latin small letter u with acute 

373 251 FB a Latin small letter u with circumflex 

374 252 FC U Latin small letter u with diaeresis 

375 253 FD y Latin small letter y with acute 

376 254 FE p Latin small letter thorn 

377 255 FF y Latin small letter y with diaeresis 
SEE ALSO 

ascii(7) 
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locale 


locale 


Locale—D escription of multi-language support. 


SYNOPSIS 


#include <locale.h> 


DESCRIPTION 


A locale is a set of language and cultural rules. These cover aspects such as language for messages, different character sets, 
lexigraphic conventions, and so on. A program needs to be ableto determine its locale and act accordingly to be portable to 
different cultures. 


The header <locale.h> declares data types, functions and macros that are useful in this task. 


The functions it declares are setlocale() to set the current locale and localeconv() to get information about number 
formatting. 


There are different categories for local information a program might need; they are declared as macros. Using them as the 
first argument to the setlocale() function, it is possible to set one of these to the desired locale: 


LC_COLLATE This is used to change the behavior of the functions strco11() and strxfrm(), which 
are used to compare strings in the local alphabet. For example the German sharp sis 
sorted as “ss.” 

LC_TYPE T his changes the behavior of the character handling and classification functions, 


such aS isupper() and toupper() and the multi- byte character functions such as 
mblen() Of wctomb(). 

LC_MONETARY Changes the behavior of the information returned by localeconv(), which describes 
the way numbers are usually printed, with details such as decimal point versus 
decimal comma. 

LC_MESSAGES Changes the language messages are displayed in. 

LC_TIME Changes the behavior of the strftime() function to display the current timeina 
locally acceptable form; for example, most of Europe uses a 24-hour clock versus the 
U.S. 12-hour clock. 

LC_ALL All of the above. 





If the second argument to setlocale() isempty string for the default locale it is determined using the following steps: 


1. If thereis anon-null environment variableLc_aLL, the value of Lc_ALL is used. 

2. |fan environment variable with the same name as one of the preceding categories exists and is non-null, its value is used 
for that category. 

3. If thereisanon-null environment variable Lane, the value of LANG is used. 


Values about local numeric formatting are made availablein a struct 1conv returned by the localeconv() function, which has 
the following declaration: 


struct lconv 

{ 

/* Numeric (non-monetary) information. */ 

char *decimal_point; /* Decimal point character. */ 

char *thousands_sep; /* Thousands separator. */ 

/* Each element is the number of digits in each group; 

elements with higher indices are farther left. 

An element with value CHAR_MAX means that no further grouping is done. 
An element with value @ means that the previous element is used for all 
groups farther left. */ 

char *grouping; 

/* Monetary information. */ 
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/* First three chars are a currency symbol from ISO 4217. 

Fourth char is the separator. Fifth char is ' '. */ 

char *int_curr_symbol; 

char *currency_symbol; /* Local currency symbol. */ 

char *mon_decimal_point; /* Decimal point character. */ 

char *mon_thousands_sep; /* Thousands separator. */ 

char *mon_grouping; /* Like ‘grouping’ element (above). */ 

char *positive_sign; /* Sign for positive values. */ 

char *negative_sign; /* Sign for negative values. */ 

char int_frac_digits; /* Int'l fractional digits. */ 

char frac_digits; /* Local fractional digits. */ 

/* 1 if currency_symbol precedes a positive value, @ if succeeds. */ 
char_p_cs_precedes; 
/* 1 if a space separates currency_symbol from a positive value. */ 
char_p_sep_by_space; 
/* 1 if currency_symbol precedes a negative value, @ if succeeds. */ 
char_n_cs_precedes; 
/* 1 if a space separates currency_symbol from a negative value. */ 
char_n_sep_by_space; 

/* Positive and negative sign positions: 

®@ Parentheses surround the quantity and currency_symbol. 

1 The sign string precedes the quantity and currency_symbol. 

2 The sign string succeeds the quantity and currency_symbol. 

3 The sign string immediately precedes the currency_symbol. 

4 The sign string immediately succeeds the currency_symbol. */ 
char_p_sign_posn; 

char_n_sign_posn; 

}; 


CONFORMS TO 
POSIX.1 


At the moment, the only locales supported by Linux are the portable c, posrx (identical to the C locale), 1so-8859-1 
(European Latin-1), and kor-8 (Russian) locales. 


SEE ALSO 


setlocale(3), localeconf(3), locale(1), localedet(1) 
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mailaddr 


mailaddr— M ail addressing description. 


DESCRIPTION 


M ail addresses are based on the ARPAN ET protocol listed at the end of this manual page. T hese addresses are in the general 
format 


user @do main 


A domain isahierarchical dot separated list of subdomains. For example the address 
eric@monet.berkeley.edu 
is usually interpreted from right to left. The message should go to the ARPA name tables (which do not correspond exactly 


to the physcal ARPAN ET) and then to the Berkeley gateway, after which it should go to the local host monet. W hen the 
message reaches monet, it is delivered to the user eric. 


mailaddr 


Unlike some other forms of addressing, this does not imply any routing. T hus, although this address is specified as an ARPA 
address, it might trave by an alternate route if that were more convenient or efficient. For example, at Berkeley, the 
associated message would probably go directly to monet over the Ethernet rather than go via the Berkeley ARPAN ET 
gateway. 


ABBREVIATION 


Unde certain circumstances, it might not be necessary to type the entire domain name. In general, anything following the 
first dot may be omitted if it is the same as the domain from which you are sending the message For example, a user on 
calder.berkeley.edu could send to ericemonet without adding the berkeley.edu because it is the same on both sending and 
receiving hosts. 


Certain other abbreviations may be permitted as special cases. For example, at Berkeley, ARPAN ET hosts may be referenced 
without adding the berkeley. edu aSlong as their names do not conflict with alocal host name. 


COMPATIBILITY 


Certain old address formats are converted to the new format to provide compatibility with the previous mail system. In 
particular, 


user @host .ARPA 
is allowed and 
host :user 
is converted to 
user @host 
to be consistent with the rcp(1) command. 
Also, the syntax 
host luser 
is converted to 
user @host .UUCP 
Thisis usually converted back to thehost !user form before being sent on for compatibility with older UU CP hosts. 
Thecurrent implementation isnot able to route messages automatically through the U UCP network. Until that time you 
must explicitly tell the mail system which hosts to send your message through to get to your final destination. 
CASE DISTINCTIONS 


Domain names (anything after the e sign) may be given in any mixture of uppercase and lowercase with the exception of 
UUCP hostnames. M ost hosts accept any combination of casein usernames, with the notable exception of muLTics sites. 


ROUTE-ADDRS 


Under some circumstances, it might be necessary to route a message through several hoststo get it to the final destination. 
Usually, this routing is done automatically, but sometimes it is desirable to route the message manually. Addresses that show 
these relays are termed “route-addrs.” T hese use the syntax 


<@hosta,@hostb:user@hostc> 
This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. This path is forced even if 
there isa more efficient path to hostc. 


Route-addrs occur frequently on return addresses because these are generally augmented by the software at each host. It is 
generally possible to ignoreall but theuser @domain part of the address to determine the actual sender. 
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POSTMASTER 


Every site is required to havea user or user alias designated “postmaster” to which problans with the mail system may be 
addressed. 


OTHER NETWORKS 


Some other networks can be reached by giving the name of the network as the last component of thedomain. Thisisnot a 
standard feature and might not be supported at all sites. For example messages to CSN ET or BITNET sites can often be 
sent to user @host .CSNET OF user @host .BITNET. 


BUGS 


TheRFC 822 group syntax (group :userl ,user2 ,user3;) isnot Supported except in the special case of group: ; because of a 
conflict with old berknet-style addresses. 


Route-Address syntax is grotty. 
UUCP- and ARPAN ET-style addresses do not coexist politely. 


SEE ALSO 
mail(1), sendmail(8); Crocker, D. H., Standard for the Format of Arpa Internet T ext M essages, RFC 822. 


14 February 1989 


man 


man— M acros to format man pages. 


SYNOPSIS 


groff -Tascii -man file ... 
groff -Tps -manfile ... 
man [section] title 


DESCRIPTION 


This manual page explains the groff tmac.an macro package. T his macro package should be used by devdopers when writing 
or porting man pages for Linux. It is fairly compatible with other versions of this macro package, so porting man pages 
should not be a major problem (exceptions include the N ET-2 BSD rdease, which uses a totally different macro package). 


N ote that NET-2 BSD man pages can be used with grotf simply by specifying the -mdoc option instead of the -man option. 
Using the -mandoc option is, however, recommended because this automatically detects which macro package isin use 


PREAMBLE 
The first command in aman page should be 


-TH title section date source manual , 


title The title of the man page (such as man). 

section Thesection number the man page should be placed in (such as7). 

date The date of the last revision; renember to change this every timea changeis made 
to the man page because this isthe most general way of doing version control. 

source The source of the command. 
For binaries, usesomething such aaGNU, NET-2, SLS Distribution, MCC 
Distribution. 


For system calls, use the version of the kernel that you are currently looking at: 


Linux 0.99.11. 


For library calls, usethe source of the function: GNU, BSD 4.3, Linux DLL 4.4.1. 
manual The title of the manual (such as Linux Programme's M anual). 


The manual sections are traditionally defined as follows: 


1 Commands Those commands that can be executed by the user from within a shell. 

2 System calls T hose functions that must be performed by the kernel. 

3 Library calls M ost of the 1ibe functions, such as sort(3). 

4 Special files Files found in /dev. 

5 File formats and conventions The format for /etc/passwd and other human-readable files. 

6 Games 

7 Macro packages and conventions A description of the standard file system layout, this man page, and other things. 
8 System management commands Commands such as mount(8), which only root can execute. 

9 Kernd routines This is anon-standard manual section and is included because the source code to 


the Linux kernel is freely available under the GN U Public License and many 
people are working on changes to the kernd.. 


FONTS 


Although there are many arbitrary conventions for man pages in the UN 1X world, the existence of several hundred Linux- 
specific man pages defines the standards: 


For functions, the arguments are always specified using italics, even in thesynopsts section, where the rest of the function is 
specified in bold: 


int myfunction(int argc, char **argv); 


Filenames are always in italics (such as /usr/include/stdio.h), except in the synopsts section, where included files are in bold 
(such aS #include <stdio.h>). 

Special macros, which are usually in uppercase, are in bold (such aS MaxInT). 

W hen enumerating alist of error codes, the codes are in bold (this list usually uses the .TP macro). 


Any reference to another: man page (or to the subject of the current man page) isin bold. If the manual section number is 
given, it is given in roman, without any spaces (such as man(7)). 


The commands to select the typeface are given below: 


.B Bold 

.BI Bold alternating with italics 
.BR Bold alternating with Roman 
I Italics 

.IB Italics alternating with bold 
LIR Italics alternating with Roman 
.RB Roman alternating with bold 
RI Roman alternating with italics 
.SB Small alternating with bold 
.SM Small 


Traditionally, each command can have up to six arguments, but theGN U version seems to remove this limitation. 
Arguments are delimited by spaces. D ouble quotes can be used to specify an argument that contains spaces. All the 
arguments will be printed next to each other without intervening spaces, so that the .8k command can be used to specify a 
word in bold followed by a mark of punctuation in Roman. 
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SECTIONS 


Sections are started with .sh followed by the heading name. If the name contains spaces and appears on the same line as .sH, 
then place the heading in double quotes. Traditional headings include NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, SEE ALSO, 
DIAGNOSTICS, BUGS, and AUTHOR. T he only required heading isname, which should be followed on the next line by aoneline 
description of the program: 


.SH NAME 
chess \- the game of chess 


It is extrenely important that this format is followed and that there is a backslash before the single dash that follows the 
command name. T his syntax is used by the makewhatis(8) program to create a database of short command descriptions for 
the whatis(1) and apropos(1) commands. 


OTHER MACROS 
O ther macros include the following: 
.DT D efault tabs. 
HP Begin hanging indent. 
.IP Begin paragraph with hanging tag. This is the same as .tP, except the tag is given on the 
same line, not on the following line. 
.LP Same as .PP. 
.PD Se interparagraph distance to argument. 
.PP Begin anew paragraph. 
.RE End relative indent (indented paragraph). 
.RS Start relative indent (indented paragraph). 
.SS Subheading (like .sH but used for a subsection). 
.TP Begin paragraph with hanging tag. T he tag is given on the next line Thiscommand is 
similar to .1P. 
FILES 
/usr/local/lib/groff/tmac/tmac.an 
/usr/man/whatis 
SEE ALSO 


groff(1), man(1), whatis(1), apropos(1), makewhatis(8) 
Linux, 25 July 1993 


signal 


signal— List of available signals. 


DESCRIPTION 


Linux supports the signals listed in this section. Several signal numbers are architecture dependent. First are the signals 
described in PO SIX.1: 


abort(3) alarm(1) N ext various other signals. 


(H eve, - denotes that a signal is absent; there, where three values are given, the first one is usually valid for alpha and sparc, 
the middle one for i386 and ppc, the last onefor mips. Signal 29 is staInFo/stcpwr on an alpha but siGLosT on a sparc.) 


suffixes 


The letters in the Action column have the following meanings: 


A D efault action is to terminate the process. 

B D efault action is to ignore the signal. 

C Default action isto dump core. 

D Default action is to stop the process. 

E Signal cannot be caught. 

F Signal cannot be ignored. 

G Not aPO SIX.1 conformant signal. 
CONFORMING TO 

POSIX.1 
BUGS 


s1Gzo and sreLost have the same value The latter is commented out in the kernel source, but the build process of some 
software still thinks that Signal 29 is steLosT. 


SEE ALSO 
kill(1), kil1(2), setitimer(2) 
Linux 1.3.88, 14 April 1996 


Suffixes 


suffixes— List of file suffixes. 


DESCRIPTION 


It iscustomary to indicate the contents of a file with thefile suffix, which consists of a period followed by one or more 
letters. M any standard utilities, such as compilers, use this to recognize the type of file they are dealing with. The make(1) 
utility is driven by rules based on file suffixes. 


Following isa list of suffixes that are likely to be found on a Linux system: 





Suffix FileT ype 

Vv Files for RCS (Revision Control System) 
Backup file 

eG C ++ source code 

F FORTRAN source with cpp(1) directives 
5S Assembler source with cpp(1) directives 
Z File compressed using compress(1) 
[0-9]+pk TeX font files 

[1-9] M anual page for the corresponding section 
{1-9][a-z] M anual page for section plus subsection 
a Static object code library 

vafm PostScript font metrics 

arc ARC archive 

ar AR] archive 

.asc PGP ASCIl-armored data 


continues 
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Suffix FileT ype 

.awk AWK language program 

.bak Backup file 

om Bitmap source 

C C source 

cat M essage catalog files 

CC C ++source 

cf Configuration file 

.conf Configuration file 

.config Configuration file 

.cweb Donald Knuth’s W EB for C 

dat Data file 

def M odula-2 source for definition modules 
def O ther definition files 

diff ASCII File differences 

.doc Documentation file 

dvi TeX device independent output 

al EMACS lisp source 

Alc Compiled EM ACS lisp 

.e0S Encapsulated PostScript 

f FORTRAN source 

fas Precompiled common lisp 

fi FORTRAN include files 

gif Graphics Interchange Format 

Lost Ghostscript fonts 

QZ File compressed using gzip(1) 

A C or C++header files 

Ip H elp file 

Atm HTML file imported without renaming from a brain-damaged OS 
.Atm| HTML document used with the W orld W ide W eb 
J C source after preprocessing 

idx Reference or datum-index file for hypertext or database system 
icon Bitmap source 

.image Bitmap source 

in Configuration tenplate, especially for GN U autoconf 
info Files for the EM ACS info browser 

java A Java source file 

Jpg JPEG compressed picture format 

; lex(1) or flex(1) files 

lib Common lisp library 

In Files for use with 1int(1) 

Isp Common lisp source 

m4 m4(1) source 

mac M acro files for various programs 


suffixes [2s] 





Suffix File T ype 

man M anual page (usually source rather than formatted) 
me nroff source using the me macro package 
mf M etafont (font generator for T eX) source 
mm Sources for groff(1) in mn format 

.mod M odula-2 source for implementation modules 
0 O bject file 

.old Old or backup file 

orig Backup (original) version of afile from patch(1) 
out Output file often an executable program (a. out) 
.p Pascal source 

.patch File differences from patch(1) 

.pcf X11 font files 

.pfa PostScript font definition files, ASCII format 
.pfb PostScript font definition files, binary format 
.pgp PGP binary data 

.pid Fileto storedaemon PID (such aS crond.pid) 
.png Portable N etwork Graphics file 

pl Perl script 

.pr Bitmap source 

.ps PostScript file 

w RATFOR source (obsolete) 

re Patches that patch(1) couldn't apply 

ules Rules for something 

S Assembler source 

sa Stub libraries for a.out shared libraries 

SC sc(1) spreadsheet commands 

sh sh(1) scripts 

shar Archive created by the shar(1) utility 

SO DLL dynamic library 

sqm SQM L schema or query program 

sty Lal eX style files 

sym M odula-2 compiled definition modules 

tar Archive created by the tar(1) utility 

tar.Z tar archive compressed with compress(1) 
tar.gz tar archive compressed with gzip(1) 

taz tar archive compressed with compress(1) 

tex TeX or LaT eX source 

texi Equivalent to .texinfo 

texinfo TeXinfo documentation source 

.tfm TeX font metrics 

.tgz tar archive compressed with gzip(1) 

.tmpl Template files 


continues 
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Suffix FileT ype 
txt Text file 
.uue Binary file encoded with uuencode(1) 
.web Donald Knuth’sW EB 
y yace(1) Or bison(1) (parser generator) files 
Z File compressed using pack(1) (or an old gzip(1)) 
.Z00 ZOO archive 
. EMACS or patch backup file 
rc Startup (run control) file, such as .newsre 
CONFORMS TO 
General UNIX conventions. 
BUGS 
This list is not exhaustive. 
SEE ALSO 


file(1), make(1) 
Linux, 4 April 1996 


tr2tex 


tr2tex— Convert adocument from trotf to LaTex 


SYNOPSIS 
tr2tex [ -m ] filename 
DESCRIPTION 


tr2tex converts a document typeset in troff to a Lal eX format. It is intended to do the first pass of the conversion. T he user 
should then finish up the rest of the conversion and customize the converted manuscript to his or her liking. It can also serve 
as a tutor for those who want to convert from troff to Lal eX. 


M ost of the converted document will bein LaT eX, but some of it may bein plain T eX. It will also use some macrosin 
troffms.sty OF troffman.sty, which are included in the package and must be available to the document when processed with 
LaTex. 


If thereis more than one input file, they will all be converted into oneLaT eX document. 


tr2tex understands most of the -ms and -man macros and eqn preprocessor symbols. It also understands several plain troff 
commands. F ew tbl preprocessor commands are understood to help convert very simple tables. 


W hen converting manuals, use the -m flag. 
If a troff Command cannot be converted, the line that contain that command will be commented out. 


N ote that if you have eqn symbols, you must have the inline mathematics ddimiter defined by de1im in the file you are 
convetting. If it is defined in another setup file, that setup file must be concatenated with the file to be converted; otherwise, 
tr2tex regards the inline math as ordinary text. 


Unicode Ea 
BUGS 


M any of these bugs are harmless. M ost of then cause local errors that can be fixed in the converted manuscript. 


m Somemacros and macro arguments are not recognized. 

m Commands that are not separated from their argument by a space are not properly parsed (such as .sp3i). 

m Whe some operators (notably over, sub, and sup) are renamed (Via define) and then they are encountered in the text, 
tr2tex treats then as ordinary macros and does not apply ther rules. 

HM rpile, lpile, and cpile are treated the same aS cpile. 

HM rcol and 1col are treated the same aS ccol. 

m Math-mode size, gsize, fat, and gfont areignored. 

HM lineup and mark areignored. T herules are so different. 

m Sometroff commands are translated to commands that require delimiters that have to be explicitly put. Because they 
are sometimes not put in trot, they can create problens. Example: .nf isnot closed by . fi. 

m Wha local motions are converted to nraise OF nlower, an nhbox is needed, which must be put manually after the 
conversion. 

M a sub i sub j isconverted toa_i_j, which TeX parsesaSa_i{}_j} with acomplaint that it is vague. a sub {i subj} is 
parsed correctly and converted to a_{i_j}. 

m Line spacing is not changed within a paragraph in T eX (which is a bad practice anyway). T eX uses the last line spacing 
in effect in that paragraph. 


TO DO 


Access registers via the .nr command. 


SEE ALSO 


texmatch(9), trmatch(9) 


AUTHOR 
Kamal Al-Y ahya, Stanford U niversity 
1 January 1987 


Unicode 


Unicode—T he unified 16-bit super character set. 


DESCRIPTION 


The international standard |SO 10646 defines the U niversal Character Se& (UCS). UCS contains all the characters of all 
other character-set standards. It also guarantees round-trip compatibility; conversion tables can be built such that no 
information is lost when a string is converted from any other encoding to UCS and back. 


UCS contains the characters required to represent almost all Known languages. T his includes apart from the many languages 
that use extensions of the Latin script also the following scripts and languages: Greek, Cyrillic, H ebrew, Arabic, Armenian, 
Gregorian, Japanese Chinese, H iragana, K atakana, Korean, H angul, D evangari, Bengali, Gurmukhi, Gujarati, O riya, T amil, 
Tdugu, Kannada, M alayam, T hai, Lao, Bopomofo, and anumber of others. W ork is going on to include further scripts such 
as Tibetan, Khmer, Runic, Ethiopian, Hieroglyphics, various Indo-European languages, and many others. For most of these 
latter scripts, it was not yet clear how they can be encoded best when the standard was published in 1993. In addition to the 
characters required by these scripts, also alarge number of graphical, typographical, mathematical, and scientific symbols 
such as those provided by T eX, PostScript, MS-DOS, Macintosh, Videotext, OCR, and many word processing systems have 
been included, as well as special codes that guarantee round-trip compatibility to all other existing character-set standards. 
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TheUCS standard (ISO 10646) describes a 31-bit character-set architecture however, today only the first 65534 code 
positions (0x0000 to Oxfffd), which are called the Basic M ultilingual Plane (BM P), have ben assigned characters, and it is 
expected that only very exotic characters (such as H ieroglyphics) for special scientific purposes will ever get a place outside 
this 16-bit BM P. 


TheUCS characters 0x0000 to 0x007f are identical to those of the classic US-ASCI| character set and the characters in the 
range 0x0000 to OxOOff are identical to thosein the|SO 8859-1 Latin-1 character set. 


COMBINING CHARACTERS 


Some code points in UCS have been assigned to combining characters. T hese are similar to the non-spacing accent keys on a 
typewriter. A combining character just adds an accent to the previous character. The most important accented characters 
have codes of thar own in UCS; however, the combining character mechanism allows you to add accents and other 
diacritical marks to any character. The combining characters always follow the character that they modify. For example, the 
German character U mlaut-A (“Latin capital letter A with diaeresis”) can either be represented by the precomposed UCS code 
0x00c4 or alternately asthe combination of anormal “Latin capital letter A” followed by a “combining diaeresis’: 0x0041 
0x0308. 


IMPLEMENTATION LEVELS 


As not all systems are expected to support advanced mechanisms such as combining characters, |SO 10646 specifies the 
following three implementation levds of UCS: 


Leve 1 Combining characters and H angul Jamo characters (a special, more complicated encoding 
of the Korean script, where H angul syllables are coded as two or three subcharacters) are not 
supported. 

Level 2 Like level 1, except in some scripts, some combining characters are now allowed (such as 


H ebrew, Arabic, D evangari, Bengali, Gurmukhi, Gujarati, O riya, Tamil, T elugo, Kannada, 
M alayalam, Thai, and Lao). 


Level 3 All UCS characters are supported. 


The Unicode 1.1 standard published by the Unicode Consortium contains exactly the UCS Basic M ultilingual Plane at 
implementation Level 3, asdescribed in ISO 10646. U nicode 1.1 also adds some sanantical definitions for some characters 
to the definitions of ISO 10646. 


UNICODE UNDER LINUX 


Under Linux, only the BM P at implementation Level 1 should be used at the moment to keep the implementation 
complexity of combining characters low. The higher implementation levels are more suitable for special word processing 
formats but not asa generic system character set. The C type wehar_t ison Linux an unsigned 16-bit integer type and its 
values are interpreted as UCS Led 1 BMP codes. 


The locale setting specifies whether the system character encoding is UTF-8 or ISO 8859-1, for example Library functions 
such aS wetomb, mbtowc, OF wprintf can be used to transform the internal wchar_t characters and strings into the systten 
character encoding and back. 


PRIVATE AREA 


In the BM P, the range 0xe000 to Oxf8ff will never be assigned any characters by the standard and is reserved for private 
usage. For the Linux community, this private area is subdivided further into the range 0xe000 to Oxefff, which can be used 
individually by any end user and the Linux zonein the range Oxf000 to Oxf8ff where extensions are coordinated among all 
Linux users. The registry of the characters assigned to the Linux zoneis currently maintained by H. Peter Anvin 

(Peter. Anvin@linux.org), Yggdrasil Computing, Inc. It contains someDEC VT 100 graphics characters missing in U nicode 
gives direct access to the characters in the console font buffer, and contains the characters used by a few advanced scripts such 
as Klingon. 


UTF-8 [2 | 
LITERATURE 


Information technology— U niversal M ultiple-O ctet Coded Characte Se (U CS). Part 1: Architecture and Basic M ultilingual 
Plane. International Standard ISO 10646-1, International Organization for Standardization, Geneva, 1993. 


Thisis the official specification of UCS. Pretty official, pretty thick, and pretty expensive. For ordering information, check 
www.iso.ch. 

T heU nicode Standard— Worldwide Character Encoding Verson 1.0. The Unicode Consortium, Addison-W esley, Reading, 
MA, 1991. 

There is already U nicode 1.1.4 available T he changes to the 1.0 book are available from ftp. unicode.org. Unicode 2.0 will 
be published again as a book in 1996. 

S. H arbison, G. Steele. C, A ReferenceM anual. Fourth edition, Prentice H all, Englewood Cliffs, 1995, 

ISBN 0-13-326224-3. 

A good reference book about the C programming language. The fourth edition now covers also the 1994 Amendment 1 to 
thelSO C standard (ISO/IEC 9899:1990), which adds a large number of new C library functions for handling wide 
character sets. 


BUGS 


At the time when this man page was written, the Linux 1ibc support for UCS was far from complete. 


AUTHOR 


M arkus Kuhn (mskuhn@cip. informatik.uni-erlangen.de) 


SEE ALSO 


utf -8(7) 
Linux, 27 D ecanber 1995 


UTF-8 


utr -8— An ASC II-compatible multibyte U nicode encoding. 


DESCRIPTION 


TheU nicode character set occupies a 16-bit code space. T he most obvious U nicode encoding (known as U CS-2) consists of 
a sequence of 16-bit words. Such strings can contain as parts of many 16-bit characters bytes such as \@ or /, which havea 
special meaning in filenames and othe C library function parameters. In addition, the majority of UN IX tools expects 
ASCII files and can’t read 16-bit words as characters without major modifications. For these reasons, UC S-2 is not a suitable 
external encoding of Unicode in filenames, text files, environment variables, and so on. The!SO 10646 Universal Character 
Set (UCS), asuperset of Unicode, occupies even a 31-bit code space, and the obvious UC S-4 encoding for it (a sequence of 
32-bit words) has the same problems. 


TheUTF-8 encoding of Unicode and UCS does not havethese problems and is the way to go for using the U nicode 
character set under UN IX-style operating systems. 


PROPERTIES 
The UTF-8 encoding has the following nice propetties: 


UCS characters 0x00000000 to 0x0000007f (the classical U.S. ASCII characters) are encoded simply as bytes 0x00 to Ox7f 
(ASCII compatibility). This means that files and strings that contain only 7-bit ASCII characters have the same encoding 
under both ASCII and UTF-8. 

All UCS characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to Oxfd, 
so no ASCII byte can appear as part of another character and there are no problems with \o or /. 
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The lexicographic sorting order of U CS-4 strings is preserved. 
All possible 2°31 UCS codes can be encoded using UTF-8. 
The bytes Oxfe and Oxff arenever used in the U TF-8 encoding. 


The first byte of a multibyte sequence that represents a singlenon-ASCII UCS character is always in the range Oxc0 to Oxfd 
and indicates how long this multibyte sequence is. All further bytes in a multibyte sequence arein the range 0x80 to Oxbf. 
This allows easy resynchronization and makes the encoding stateless and robust against missing bytes. 


UT F-8- encoded U CS characters may be up to six bytes long; however, U nicode characters can only beup to three bytes 
long. Because Linux uses only the 16-bit U nicode subset of UCS, under Linux, UT F-8 multibyte sequences can only be one, 
two, or three bytes long. 


ENCODING 


The following byte sequences are used to represent a character. The sequence to be used depends on the UCS code number 
of the characte: 


Q@xX00000000 - Ox@QQOQQ07F: Oxxxxxxx 

Qx00000080 - Q@xQQQOO7FF: 11OxxXxxx 1OxXxXxXxxx 

Q@x00000800 - QxXQQOOFFFF: 111O0xxxx 1OxXXXXXX 1OXXXXXX 

Q@x00010000 - OxQQ1FFFFF: 11110xxx 1OxXXXxXXX TOXXXXXX 1OXXXXXX 
O@x00200000 - O@x@3FFFFFF: 111110xx 1OxXxXxXxXXX TOXXXXXX TOXXXXXX TOXXXXXX 
Q@x04000000 - OX7FFFFFFF: 1111110x 1OxxxXxXxXxX 1OXXXXXX TOXXXXXX TOXXXXXX 
TOXXXXXX 


Thexxx-bit positions are filled with the bits of the character code number in binary representation. O nly the shortest 
possible multibyte sequence that can represent the code number of the character can be used. 


EXAMPLES 
The Unicode character 0xa9 = 1010 1001 (the copyright sign) isencoded in UT F-8 as 
11000010 10101001 = @xc2 oxa9 


and character 0x2260 = 0010 0010 0110 0000 (the “not equal” symbol) is encoded as 


11100010 10001001 10100000 = Oxe2 0x89 Oxad 


STANDARDS 
ISO 10646, Unicode 1.1, XPG4, Plan 9. 


AUTHOR 


M arkus Kuhn (mskuhn@cip. informatik.uni-erlangen.de) 


SEE ALSO 


unicode(7) 
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Part VIII: Administration and Privileged Commands 


intro 


intro— Introduction to administration and privileged commands. 


DESCRIPTION 


This chapter describes commands that either can be or are only used by the superuser, such as daenons and machine or 
hardware-related commands. 


AUTHORS 


Look at the header of the manual page for the authors and copyright conditions. N ote that these can be different from page 
to page. 


Linux, 24 July 1993 


adduser, addgroup 


adduser, addgroup— Add a user or group to the system. 


SYNOPSIS 
adduser [--system [--home directory] [--group]] [--quiet] 
[--force-badname] [--help] [--version] [--debug] username 
adduser [--quiet] [--force-badname] [--help] [--version] 
[--debug] username group 
adduser [--group] [--quiet] [--force-badname] [--help] 
[--version] [--debug] group 

DESCRIPTION 


adduser and addgroup add users and groups to the systen according to information provided in the configuration file /etc/ 
adduser.conf. adduser and addgroup automatically determine the UID or GID and place the entity in the password or 
group file as appropriate. 


If necessary, adduser creates a home directory for the new user, copies “skeletal” user files to it from /etc/ske1, and allows 
the system administrator to set an initial password and finger information for the user. 


Because it needs to be able to write to such files as /etc/passwd, adduser Can only berun as root. 


Generally, there are two types of users and groups on a system: thoseuse’s that log into the system and those “non-user” 
accounts and groups that exist for various system tasks and projects. H enceforth, user will refer to the login type and system 
user or group will refer to the type used for system maintenance and projects. 


By default, each user in D ebian GNU/Linux is given a corresponding group with the same name and ID, allowing people 
easily to give access to thar home directories to others. T his option can be turned off in the configuration file, in which case 
each user is, by default, added to a group called users. 


Under Debian GNU/Linux, ID s less than or equal to 100 are allocated by the base systen maintainer for various purposes. 
ID sfrom 101 to the value specified in the configuration file (1000, by default) are used for system users and groups. |Ds 
greater than 1000 are reserved for users and their corresponding groups. 


W hen invoked with asinglename, adduser creates a user with that name When given two names, adduser assumes that the 
first name represents an existing user and that the second name represents an existing group. In this case, the user is added to 
the group. 


OPTIONS 


--system Create a system user. T his user will be assigned the shell /bin/false and have an 
asterisk in the password field. Unless otherwise specified, the user will be placed 
in thegroup nogroup. Skdetal configuration files will not be copied into the 
user’s home directory. 

--home directory W hen used with --system, this usesdi rectory astheuser’s home directory, 
rather than the default specified in the configuration file If the directory does 
not exist, it is created. 

- -group W hen combined with — system, a group with the same nameand ID asthe 
system user is created. If not combined with --system, a group with the given 
nameis created. T his isthe default action if the program is invoked as addgroup. 

--quiet Suppress progress messages. 

- - force -badname By default, user and group names are required to consist of a lowercase letter 
followed by one or more lowercase letters or numbers. T his option forces 
adduser OF addgroup to be more lenient. 


--help Display brief instructions. 

--version Display version and copyright information. 

- -debug Display a large quantity of debugging information. 
SEE ALSO 

adduser.conf(5) 
COPYRIGHT 


Copyright(c) 1995, T ed H ajek, with a great deal borrowed from the original D ebian adduser, copyright(c) 1994, lan 
Murdock. adduser is free software; see the GN U G eneval Public License version two or later for copying conditions. There is 
no warranty. 


Debian GNU /Linux version 1.94 


agetty 


agetty— Alternative Linux getty. 


SYNOPSIS 
agetty [-ihL] [-l login_program] [-m] [-t timeout] port baud_rate,... [term] 
agetty [-ihL] [-l login_program] [-m] [-t timeout] baud rate,... port [term] 
DESCRIPTION 


agetty opens atty port, prompts for alogin name, and invokes the /bin/1ogin command. It is usually invoked by init(8). 
agetty has several non-standard features that are useful for hard-wired and for dial-in lines: 


Adapts the tty settings to parity bits and to erase, kill, end-of-line, and uppercase characters when it reads a login name. 
The program can handle 7-bit characters with even, odd, none, or space parity and 8-bit characters with no parity. T he 
following special characters are recognized: e and Control+U (kill); #,D @ and Backspace (erase); carriage return and line 
feed (end of line). 


O ptionally deduces the baud rate from the connect messages produced by H ayes-compatible modems. 
O ptionally does not hang up when it is given an already opened line (useful for call-back applications). 
Optionally does not display the contents of the /etc/issue file (Systan V only). 
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O ptionally invokes a non-standard login program instead of /bin/login. 
O ptionally turns on hardware flow control. 
O ptionally forces the line to be local with no need for carrier detect. 


This program does not use the /etc/gettydefs (System V) or /etc/gettytab (SunOS 4) files. 


ARGUMENTS 


port A path name relative to the /dev directory. If a- is specified, agetty 
assumes that its standard input is already connected to atty port and that 
a connection to aremote user has already been established. Under System 
V, a- port argument should be preceded by a-. 

baud rate,... A comma-separated list of one or more baud rates. Each time agetty 
receives a break character, it advances through the list, which is treated as 
if it were circular. Baud rates should be specified in descending order, so 
that the null character (C trl-+@) can also beused for baud rate switching. 


term The value to be used for the TERM environment variable. T his overrides 
whatever init(8) may haveset and is inherited by login and the shdl. 


OPTIONS 
-h Enable hardware (RT S/CTS) flow control. It is left up to the application 
to disable software (XON/XO FF) flow protocol where appropriate. 
-i Do not display the contents of /etc/issue before writing the login 


prompt. T erminals or communications hardware might become confused 
when receiving lots of text at the wrong baud rate dial-up scripts might 
fail if the login prompt is preceded by too much text. 

-1 login_program Invoke the specified login program instead of /bin/1ogin. This allows 
the use of anon-standard login program (for example, one that asks for a 
dial-up password or that uses a different password file). 

-m Try to extract the baud rate the connect status message produced by some 
H ayes-compatible modems. T hese status messages are of the form: 
"<junk><speed><junk>". agetty assumes that the modem emits its 
status message at the same speed as specified with (the first) baud rate 
value on the command line 
Because the -m feature might fail on heavily loaded systems, you still 
should enable break processing by enumerating all expected baud rates on 
the command line 


-t timeout Terminate if no username could be read within timeout seconds. This 
option should probably not be used with hard-wired lines. 
“L Forcethe line to bea local line with no need for carrie detect. This can 


be useful when you havea locally attached terminal where the serial line 
does not set the carrier detect signal. 


EXAMPLES 
This section shows sample entries for the /etc/inittab file. 
For ahard-wired line 
tty1:con80x60:/sbin/agetty 9600 tty1 
For adial-in line with a9600/2400/1200 baud modem: 
ttyS1:dumb:/sbin/agetty -mt60 ttyS1 9600,2400,1200 


T hese examples assume you use the simpleinit(8) init program for Linux. If you usea SysV -like init (does /etc/inittab 
mention “respawn”?), refer to the appropriate manual page. 
ISSUE ESCAPES 


The/etc/issue file might contain certain escape codes to display the systen name, date and time, and so on. All escape 
codes consist of a backslash (\) immediately followed by one of the following letters: 


b Insert the baudrate of the current line. 

d Insert the current date. 

s Insert the system name, the name of the operating system. 
1 Insert thename of the current tty line 


Insert the architecture identifier of the machine, such as i486. 
Insert the nodename of the machine, also known as the hostname 
Insert the domain name of the machine. 

Insert the release number of the OS, such as 1.1.9. 


3 


=) 


° 


Ie 

t Insert the current time 

u Insert the number of current users logged in. 

U Insert thestring1 user orn users wheren isthenumber of current users logged in. 
v Insert the version of the OS, such asthe build date and so on. 


For example, on my system, the following /etc/issue file 
This is \n.\o (\s\m\r) \t 

displays as 

This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30 


FILES 
/var/run/utmp, the system status file 
/etc/issue, printed beforethe login prompt (System V only) 
/dev/console, problen reports (if sysiog(3) isnot used) 
/etc/inittab (LINUX simpleinit(8) configuration file) 


BUGS 


The baud-rate detection feature (the -m option) requires that agetty be scheduled soon enough after completion of a dial-in 
call (within 30ms with modems that talk at 2400 baud). For robustness, always use the -m option in combination with a 
multiple baud rate command-line argument so that break processing is enabled. 


The text in the /etc/issue file and the login prompt are always output with 7-bit characters and space parity. 
The baud-rate detection feature (the -m option) requires that the modem emits its status message after raising the DCD line 


DIAGNOSTICS 


Depending on how the program was configured, all diagnostics are written to the console device or reported via the 
syslog(3) facility. Error messages are produced if the port argument does not specify a terminal device, if there is no utmp 
entry for the current process (Systen V only), and so on. 


AUTHORS 


W.Z. Venema (wietse@wzv.win.tue.n1) Eindhoven University of Technology, D epartment of M athematics and C omputer 
Science Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The N etherlands. 


Peter O rbaek (poe@daimi.aau.dk), Linux port. 
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CREATION DATE 
Sat N ov 25 22:51:05 MET 1989 


LAST MODIFICATION 
91/09/01 23:22:00 


VERSIO N/ RELEASE 
1.29 


archive 


archive— Usmet article archiver. 


SYNOPSIS 


archive [ -a archive ][-f ][-i index ][-m ][-r ][input ] 


DESCRIPTION 


archive makes copies of files specified on its standard input. It isusually run either as a channel feed under inna(8) or by a 
script before expire(8) iS run. 


archive reads the named input file or standard input if no file is given. The input is taken asa set of lines. Blank lines and 
lines starting with anumber sign (#) are ignored. All other lines should specify the name of afile to archive. If a filename is 
not an absolute pathname it is taken to be rdative to /news/spool. 


Files are copied to adirectory within the archive directory, /news/spool/news.archive. T he default is to create a hierarchy 
that mimics the input files; intermediate directories are created as needed. For example, the input file comp/sources/unix/ 
2211 (article2211 in thenewsgroup comp. sources. unix) iS copied to /news/spool/news .archive/comp/sources/unix/ 
2211.1f the -+ flag is used, then all directory names are flattened out, replacing the slashes with periods. In this case the file 
is copied to /news/spool/news.archive/comp.sources.unix/2211. 


If the -i flag is used, then archive appends one line to the specified index file for each article that it copies. T his line 
contains the destination name and the M essage ID and Subject headers. 

For example, a typical newsfeeds(5) entry to archive most source newsgroups is as follows: 

source-archive\ 

:!*,*sources*,!*wanted*,!*.d\ 

:Tc ,Wn\ 

:/archive -f -i \ 

/usr/spool/news/news.archive/ INDEX 

Files are copied by making a link. If that fails, a new file is created. If the -m flag is used, then the file is copied to the 
destination, and the input file is reolaced with a symbolic link pointing to the new file. T he -m flag is ignored. 


By default, archive setsits standard error to /var/1og/news/errlog. T 0 suppress this redirection, use the -r flag. 


If the input is exhausted, archive exits with a zero status. If an 1/O error occurs, it tries to spool its input, copying it to afile. 
If there was no input filename, the standard input is copied to /news/spool/out.going/archive and the program exits. If 
an input filename was given, atenporary file named input .bch (if input isan absolute pathname) or /news/spool/ 
out.going/ input. bch (if the filaaame does not begin with a slash) is created. Once the input is copied, archivetries to 
rename this temporary file to be the name of the input file and then exits. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN &tN ews. 


SEE ALSO 


newsfeeds(5) 


arp 


arp— M anipulate the system ARP cache 
SYNOPSIS 


arp [-v] [-t type] -a [hostname] 

arp [-v] -d hostname ... 

arp [-v] [-t type] -s hostname hw addr 
arp [-v] -f filename 


DESCRIPTION 


arp Manipulates the kernel’s ARP cache in various ways. T he primary options are clearing an address mapping entry and 
manually setting up one. For debugging purposes, the arp program also allows a complete dump of the ARP cache 


OPTIONS 

“Vv Tell the user what is going on by being verbose 

-t type W hen setting or reading the ARP cache this optiona parameter tds arp which class 
of entries it should check for. The default value of this parameter is ether (hardware 
code 0x01 for IEEE 802.3 10M bps Ethernet). O ther values might include network 
technologies such as ARC net (arcnet), PRO net (pronet), and AX.25 (ax25). 

-a [hostname ] Shows the entries of the specified hosts. If thehost name parameter is not used, all 
entries are displayed. 

-d hostname Remove the entries of the specified host. T his can be used if the indicated host is 
brought down, for example 

-s hostname hw addr M anually create an ARP address mapping entry for host host name with hardware 


address set to hw_addr. T he format of the hardware address is dependent on the 
hardware class, but for most classes, you can assume that the usual presentation can 
be used. For the Ethernet class, this is six bytes in hexadecimal, separated by colons. 


-f filename Similar to the -s option, only this time the address info is taken from filefi | ename. 
This can be used if ARP entries for alot of hosts have to be set up. The name of the 
data file is often /etc/ethers, but this is not official. 


The format of the fileis simple it only contains ASCII text lines with a hostname 
and a hardware address separated by whitespace. 


In all places where a hostname is expected, you can also enter an IP address in dotted-decimal notation. 
FILES 

/proc/net/arp 

/etc/ethers 
AUTHOR 

Fred N. van Kempen (walt je@uwalt.n1.mugnet.org) 

09 June 1994 


Part VIII: Administration and Privileged Commands 
badblocks 


badblocks— Search a device for bad blocks. 


SYNOPSIS 


badblocks [ -b block-size ] [ -o output_file ] [ -v ][-w ] device blocks-count 


DESCRIPTION 


badblocks iS used to search for bad blocks on a device (usually a disk partition). device is the special file corresponding to the 
device (such as /dev/hdxx). blocks-count is the number of blocks on the device. 


OPTIONS 

-b block-size Specify the size of blocks in bytes. 

-O output _file Write the list of bad blocks to the specified file. Without this option, badblocks 
displays the list on its standard output. 

“Vv Verbose mode. 

-w Use write mode test. With this option, badblocks scans for bad blocks by writing 
some patterns (Oxaa, 0x55, Oxff, and 0x00) on every block of the device, reading 
every block and comparing the contents. 

WARNING 
N ever use the -w option on a device containing an existing filesysten. T his option erases data! 
AUTHOR 
badblocks was written by Remy Card (card@masi.ibp.fr), the develope and maintainer of theext2 fs. 
BUGS 
| had no chance to make real tests of this program because! use ID E drives, which renap bad blocks. | only made some tests 
on floppies. 
AVAILABILITY 
badblocks iS avalable for anonymous FTP from ftp.ibp.fr and tsx-11.mit.eduin /pub/1linux/packages/ext2fs. 
SEE ALSO 


e2fsck(8), mke2ts(8) 
Verdon 0.5b, N ovember 1994 


buffchan 


buffchan— Buffered file-writing back end for InterN e&tN ews. 


SYNOPSIS 


buffchan [ -b ][-c lines ][-C seconds ][-d directory ] 
[-f fields ]{-m map ][-p pidfile ][-Llines ][-L seconds ] 
[-r ][-s file format J[-u ] 


DESCRIPTION 


buffchan reads lines from standard input and copies certain fidds in each line into files named by othe fields within the 
liné buffchan isintended to be called by inna(8) as an exploder feed. 


cfdisk 


buffchan input is interpreted as a set of lines. Each line contains a fixed number of initial fidds, followed by a variable 
number of filename fields. All fidds in a line are separated by whitespace The default number of initial fiddsis one the -F 
flag may be used to specify a different number of fields. See filechan(8) for an example. 


After the initial fidds, each renaining field names a fileto write T he -s flag may beused to specify a format string that maps 
the field to afilevame This is a sprintt(3) format string, which should havea single «s parameter that is given the fidd. 
The default value is /news /spool/out.going/%s. See the description of this flag in filechan(8). T he -a flag may be used to 
specify a directory the program should change to before starting. If this flag is used, then thedefault for the -s flag is 
changed to bea simple %s. 

Once butfchan opens afile it keepsit open. The input must therefore never specify more files than the number of available 


descriptors can keep open. If the -b flag isused, the program will allocate a buffer and attach it to the file using setbut(3). If 
the -u flag isused, the program will request unbuffered output. 


If the -1 flag is used with a number n, then buffchan will call #f1ush(3) after every n lines are written to a file If the -c flag 
is used with anumber n, then buffchan will close, and reopen, a file after every n lines are written to a file. 





If the -L flag is used with anumber n, then all files will be flushed every n seconds. Similarly, the -c flag may be used to 
specify that all files should be closed and reopened every n seconds. 


By default, the program sets its standard error to /var/1log/news/errlog. T 0 suppress this redirection, use the -r flag. 
If the -p flag is used, the program will write a line containing its process|D (in text) to the specified file. 


buffchan can be invoked as an exploder feed (see newsfeeds(5)). As such, if a line starts with an exclamation point, it is 
treated as a command. T here are three commands: 


flush The flush command closes and reopens all open files; flush xxx flushes only the 
specified site. These are analogous to the ctlinna(8) flush command and can be 
achieved by doing a send flush xxx command. Applications can tal that the flush 
has completed by renaming the file before issuing the command; buffchan has 
completed the command when the original filename reappears. 
buffchan also changes the access permissions of the file from read-only for everyone 
to read-write for owner and group as it flushes or closes each output file It changes 
the modes back to read-only if it reopens the same file 

drop The drop command is similar to the flush command except that any files are not 
reopened. If given an argument, then the specified site is dropped; otherwise, all sites 
are dropped. (N ote that the site will be restarted if the input stream mentions the 
site) When actiinnd “drop site’ command is sent, inna will automatically forward 
the command to buffchan if the siteis a funnel that feeds into this explode. To 
drop all sites, use the ctlinnd send buffchan-site drop command. 


readmap The map file (specified with the -m flag) is reloaded. 
HISTORY 

Written by Rich $alz (rsalzeuunet .uu.net) for InterN &tN ews. 
SEE ALSO 


ctlinna(8), filechan(8), innd(8), newsfeeds(5). 


cfdisk 


cfdisk— Curses-based disk partition table manipulator for Linux. 


SYNOPSIS 


cfdisk [ -avz ] [ -c cylinders ][-h heads ][-s sectors-per-track ][-P opt ] 
[device ] 


Part VIII: Administration and Privileged Commands 


DESCRIPTION 

cfdisk iS a curses-based program for partitioning a hard disk drive. The device can be any one of the following: 
/dev/hda [default] 

/dev/hdb 

/dev/sda 

/dev/sdb 

/dev/sdc 

/dev/sdd 


cfdisk first triesto read the geometry of thehard dix. If it fails, an error message is displayed and cfdisk exits. T his should 
only happen when partitioning a SCSI driveon an adapter without aBIOS. To correct this problem, you can set the 
cylinders, heads, and sectors-per-track on thecommand line N ext, cfdisk tries to read the current partition table from the 
disk drive If it is unable to figure out the partition table, an error is displayed and the program exits. T his might also be 
caused by incorrect geometry information and can be overridden on the command line Another way around this problem is 
with the -z option. T his will ignore the partition table on the disk. 


The main display is composed of four sections, from top to bottom: the header, the partitions, the command line and a 
warning line. The header contains the program name and version number followed by the disk drive and its gometry. The 
partitions section always displays the current partition table. The command line is the place where commands and text are 
entered. The available commands are usually displayed in brackets. The warning line is usually enpty except when there is 
important information to be displayed. The current partition is highlighted with reverse video (or an arrow if the -a option 
is given). All partition-specific commands apply to the current partition. 


The format of the partition table in the partition’s section is, from left to right: N ame, Flags, Partition T ype, Filesysten 
Type, and Size Thenameis the partition devicename The flags can be Boot, which designates a bootable partition or NC, 
which stands for “N ot Compatible with DOS or 0 S/2.” DOS, 0 S/2, and possibly other operating systems require the first 
sector of the first partition on the disk and all logical partitions to begin on the second head. T his wastes the second through 
the last sector of the first track of the first head (the first sector is taken by the partition table itself). cfdisk allows you to 
recover these “lost” sectors with the maximize command (m). N ote that taisk(8) and some early versions of DOS create all 
partitions with the number of sectors already maximized. For more information, see the maximize command later in this 
chapter. The partition type can be Primary or Logical. For unallocated space on the drive, the partition type can also be 
Pri/Log or empty (if the space is unusable). T he filesystem type section displays the name of the filesystem used on the 
partition, if known. If it is unknown, then Unknown and the hex value of the filesystem type are displayed. A special case 
occurs when thee are sections of the disk drive that cannot be used (because all the primary partitions are used). When this 
is detected, the filesystem type is displayed as unusable. T hesize fidd displays the size of the partition in megabytes (by 
default). It can also display the size in sectors and cylinders (see the change units command later in this chapter). If an 
asterisks (*) appears after the size, this means that the partition is not aligned on cylinder boundaries. 


DOS 6.X WARNING 


TheDOS 6.x Format command looks for some information in the first sector of the data area of the partition and treats this 
information as more reliable than the information in the partition table. bos FormAT expects Dos FbDIsk to Clear the first 512 
bytes of the data area of a partition whenever a size change occurs. pos _ForMAT looks at this extra information even if the /u 
flag is given; we consider this abug in Dos FORMAT and DOS FDISK. 


The bottom lineis that if you use cfdisk Or fdisk to changethesize of aD OS partition table entry and then you must also 
use dd to zero the first 512 bytes of that partition before using pos Format to format the partition. For example, if you were 
using cfdisk to makea DOS partition table entry for /dev/hdat, then (after exiting fdisk or cfdisk and rebooting Linux 
so that the partition table information is valid), you use the command dd if=/dev/zero of=/dev/hda1 bs=512 count=1 to 
zero the first 512 bytes of the partition. 


Be extremely careful if you use the ad command because a small typo can make all of the data on your disk usdess. 


For best results, you should always use an O S-specific partition table program. For example, you should makeDOS 
partitions with the bos FDISK program and Linux partitions with the Linux fdisk or Linux cfdisk program. 


cfdisk 
COMMANDS 


cfdisk commands can be entered by pressing the desired key (pressing Enter after the command is not necessary). H ereisa 
list of the available commands: 


b T oggle bootable flag of the current partition. T his allows you to select which primary partition is 
bootable on the drive. 
d D elete the current partition. T his will convert the current partition into free space and merge it 


with any free space immediately surrounding thecurrent partition. A partition already marked as 
free space or marked as unusable cannot be deleted. 

g Change the disk geometry (cylinders, heads, or sectors-per-track). Warning: This option should 
only be used by people who know what they are doing. A command-line option is also available to 
change the disk geometry. W hile at the change disk geometry command line, you can choose to 
change cylinders (a), heads (h), and sectors per track (s). T he default value will be printed at the 
prompt, which you can accept by simply pressing the Enter key or you can exit without changes by 
pressing the Esc key. If you want to change the default value, simply enter the desired value and 
press Enter. The altered disk parameter values do not take effect until you return to the main menu 
(by pressing Enter or Esc at the change disk geometry command line If you change the geometry 
such that the disk appears larger, the extra sectors are added at the end of the disk as free space If 
the disk appears smaller, the partitions that are beyond the new last sector are deleted and the last 
partition on the drive (or the free space at the end of thedrive) is made to end at the new last 


sector. 
h Print the help screen. 
m M aximize disk usage of the current partition. This command will recover the the unused space 


between the partition table and the beginning of the partition, at the cost of making the partition 
incompatible with DOS, 0 S/2, and possibly other operating systems. T his option will toggle 
between maximal disk usage and DOS, 0 S/2, and so on compatible disk usage. T he default when 
creating a partition is to create DOS, 0/2, and so on compatible partitions. 

n Create new partitions from free space. If the partition type is Primary Or Logical, a partition of 
that type will be created, but if the partition type is Pri/Log, you will be prompted for the type you 
want to create. Be aware that there are only four slots available for primary partitions and because 
there can be only one extended partition that containsall of the logical drives, all of the logical 
drives must be contiguous (with no intervening primary partition). cfdisk next prompts you for 
the size of the partition you want to create The default size, equal to the entire free space of the 
current partition, is displayed in megabytes. You can ather press the Enter key to accept the default 
size or enter a different size at the prompt. cfdisk accepts size entries in megabytes (m) (default), 
kilobytes (k), cylinders (d), and sectors (s) when you enter the number immediately followed by m, 
k, c, or s. If the partition fills the free space available, the partition is created and you are returned 
to the main command line. O therwise the partition can be created at the beginning or the end of 
the free space and cfdisk will ask you to choose where to place the partition. After the partition is 
created, cfdisk automatically adjusts the other partition’s partition types if all of the primary 








partitions are used. 

p Print the partition table to the screen or to afile. T here are several different formats for the 
partition that you can choose from: 

r Raw data format (exactly what would be written to disk). 

s Partition table in sector order format. 

t Partition table in raw format. The raw data format will print the sectors that would be written to 
disk if awrite command isselected. First, the primary partition table is printed, followed by the 
partition tables associated with each logical partition. T he data is printed in hex byte-by-byte with 


16 bytes pe line The partition table in sector order format will print the partition table ordered by 
sector number. The fields, from left to right, are the number of the partition, the partition type, the 
first sector, the last sector, the offset from the first sector of the partition to the start of the data, the 
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Up arrow, D own arrow 


Ctri4L 


? 


length of the partition, the filesystem type (with the hex value in parentheses), and the flags (with 
the hex value in parentheses). In addition to the primary and logical partitions, free and unusable 
space is printed and the extended partition is printed before the first logical partition. 

If a partition does not start or end on acylinder boundary or if the partition length is not divisible 
by the cylinder size, an asterisk (*) is printed after the non-aligned sector number/count. T his 
usually indicates that a partition was created by an operating system that eather does not align 
partitions to cylinder boundaries or that used different disk geometry information. If you know the 
disk geometry of the other operating system, you can enter the geometry information with the 
change geometry command (g). 

For the first partition on the disk and for all logical partitions, if the offset from the beginning of 
the partition is not equal to the number of sectors per track (that is, the data does not start on the 
first head), anumber sign (#) is printed after the offset. For the renaining partitions, if the offset is 
not zero, anumber sign is printed after the offset. T his corresponds to the nc flag in the partitions 
section of the main display. 

The partition table in raw format will print the partition table ordered by partition number. It will 
leave out all free and unusable space. T he fields, from left to right, are the number of the partition, 
the flags (in hex), the starting head, sector, and cylinder, the filesystem ID (in hex), the ending 
head, sector, and cylinder, the starting sector in the partition, and the number of sectors in the 
partition. Theinformation in this table can be directly translated to the raw data format. The 
partition table entries only have 10 bits available to represent the starting and ending cylinders. 
Thus, when the absolute starting (ending) sector number is on acylinder greater than 1023, the 
maximal values for starting (ending) head, sector, and cylinder are printed. T his is the method used 
by 0S/2, and it fixes the problems associated with O S/2’s fdisk rewriting the partition table when 
it isnot in this format. Because Linux and O S/2 use absolute sector counts, the values in the 
starting and ending head, sector, and cylinder are not used. 

Quit program. This will exit the program without writing any data to disk. 

Change thefilesysten type. By default, new partitions are created as Linux partitions, but because 
cfdisk Can create partitions for other operating systems, changing the partition type allows you to 
enter the hex value of the filesystem you desire. A list of the known filesystem types is displayed. 
You can type the filesystem type at the prompt or accept the default filesysten type (Linux). 
Change units of the partition size display. It will rotate through megabytes, sectors, and cylinders. 
W rite partition table to disk (you must enter an uppercase w). Because this might destroy data on 
the disk, you must either confirm or deny the write by entering yes or no. If you enter yes, cfdisk 
will write the partition table to disk and the tell the kernal to reread the partition table from the 
disk. T he re-reading of the partition table works in most cases, but | have seen it fail. D on’t panic. 
It will be correct after you reboot the system. In all cases, | still recommend rebooting the system 
just to be safe. 

M ove cursor to the previous or next partition. If there are more partitions than can be displayed on 
a screen, you can display the next (previous) set of partitions by moving down (up) at the last (first) 
partition displayed on the screen. 

Redraws the screen. In case something goes wrong and you cannot read anything, you can refresh 
the screen from the main command line. 


Print the help screen. 


All the commands can be entered with either uppercase or lowercase letters (except for writes). When in asubmenu or at a 
prompt to enter a filename, you can hit the Esc key to return to the main command line. 


OPTIONS 


a 


A 


Use an arrow cursor instead of reverse video for highlighting the current partition. 
Print the version number and copyright. 


-Z Start with zeroed partition table. This option is useful when you want to repartition 
your entire disk. N ote that this option does not zero the partition table on the disk; 
rather, it simply starts the program without reading the existing partition table. 

-c cylinders 

-h heads 


-s sectors-per-track Override thenumber of cylinders, heads, and sectors-per-track read from the BIOS. If 
your BIOS or adapter does not supply this information or if it supplies incorrect 
information, use these options to set the disk geometry values. 


-P opt Prints the partition table in specified formats. opt can be one or more of r, s, or t. See 
the print command for more information on the print formats. 


SEE ALSO 


fdisk(8) 


BUGS 


The current version does not support multiple disks (future addition). 


AUTHOR 
Kevin E. Martin (martin@cs.unc.edu) 
TheBOGUS Linux Rdeas, 3 June1995 


chat 


chat— Automated conversational script with amodem. 


SYNOPSIS 


chat [ options ] script 


DESCRIPTION 


The chat program defines a conversational exchange betwen the computer and the modem. Its primary purposeis to 
establish the connection between the Point-to-Point protocol daemon (pppd) and the remote’s pppd process. 


OPTIONS 
-f <chat file> Read the chat script from the chat file The use of this option is mutually exclusive with 
the chat script parameters. The user must have read access to the file M ultiple lines are 
permitted in the file Space or horizontal tab characters should be used to separate the 
strings. 
-t <timeout > Se the time-out for the expected string to be received. If the string is not reca ved 


within the timelimit, then the reply string is not sent. An alternate reply may be sent or 
the script will fail if there is no alternate reply string. A failed script will cause the chat 
program to terminate with a nonzero error code. 

-r <report file> Se the file for output of the report strings. If you use the keyword report, the resulting 
strings are written to thisfile. If this option is not used and you still use REPORT 
keywords, the stderr file is used for the report strings. 

“Vv Request that the chat script be executed in a verbose mode T he chat program will then 
log all text recaved from the modem and the output strings that it sends to the sysLoe. 
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-V Request that the chat script be executed in a stderr verbose mode The chat program 
will then log all text received from the modem and the output strings that it sends to the 
stderr device T his device is usually the local console at the station running the chat or 
pppd program. Thisoption does not work properly if the stderr is redirected to the / 
dev/null location because in that case pppd should run in the detached mode. In that 
case, use the -v option to record the session on the sysLoa device. 

script If the script is not specified in a file with the -f option, then the script is included as 
parameters to the chat program. 


CHAT SCRIPT 
The chat script defines the communications. 
A script consists of one or more “expect-send” pairs of strings, separated by spaces, with an optional “subexpect-subsend” 
string pair, separated by a dash asin thefollowing example: 
ogin: -BREAK-ogin: ppp ssword: hello2u2 
This line indicates that the chat program should expect the string ogin:. If it fails to receive alogin prompt within the time 


interval allotted, it isto send a break sequence to the remote and then expect the string ogin:. If the first ogin: is received, 
then the break sequence is not generated. 


Onceit receives the login prompt, the chat program will send the string ppp and then expect the prompt ssword:. When it 
receives the prompt for the password, it will send the password he1lo2v2. 

A carriage return is usually sent following the reply string. It isnot expected in the “expect” string unless it is specifically 
requested by using the nr character sequence. 


The expect sequence should contain only what is needed to identify the string. Because it is usually stored on a disk file it 
should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, 
or other variable pieces of data such as an expect string. 


To hap correct for characters that may be corrupted during the initial sequence look for the string ogin: rather than 
login:. It is possible that the leading 1 character might be received in error and you might never find the string even though 
it was sent by the system. For this reason, scripts look for ogin: rather than login: and ssword: rather than password:. 

A very simple script might look like this: 

ogin: ppp ssword: hello2u2 

In other words, expect ....ogin:, send ppp, expect ...ssword:, Send hello2u2. 

In actual practice, simple scripts are rare. At the vary least, you should include subexpect sequences in case the original string 
isnot received. For example, consider the following script: 

ogin:-ogin: ppp ssword: hello2u2 

Thisis a better script than the simple one used earlier. This looks for the same login: prompt; however, if one was not 


received, a single return sequence is sent and then it will look for 1ogin: again. Should line noise obscure the first login 
prompt then sending the empty line will usually generate a login prompt again. 


ABORT STRINGS 


M any modems will report the status of the call as a string. T hese strings may be CONNECTED Or NO CARRIER OF Busy. It is 
often desirable to terminate the script if the modem fails to connect to the remote. The difficulty is that a script does not 
know exactly which moden string it might receive. Orn oneattempt, it might receiveBusy, but the next time, it might 
receive NO CARRIER. 


T hese “abort” strings can be specified in the script using the aBorT sequence. It is written in the script as in the following 
example: 


ABORT BUSY ABORT 'NO CARRIER' " ATZ OK ATDT5551212 CONNECT 
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T his sequence will expect nothing and then send the string AT Z. T he expected response to this is the string ox. W hen it 
receives ok, the string ATDT5551212 dials the telephone. T he expected string is connect. If the string Connect is received, the 
remainder of the script is executed. H owever, if the modem finds a busy telephone, it sends the string Busy. T his causes the 
string to match the abort character sequence. The script then fails because it found a match to the abort string. If it recaved 
the string No CARRIER, it aborts for the same reason. Either string may be recaved. Either string will terminate the chat 
script. 


REPORT STRINGS 


A report string is similar to the aBort string. T he difference is that the strings and all characters to the next control character 
such as a carriage return, are written to the report file. 


The report strings may be used to isolate the transmission rate of the modem’s connect string and return the value to the chat 
user. The analysis of the report string logic occurs in conjunction with the other string processing such as looking for the 
expect string. The use of the same string for areport and abort sequence is probably not very useful; however, it is possible. 


Thereport strings do not change the completion code of the program. 


These “report” strings may be specified in the script using therEPorT sequence It is written in the script as in the following 
example: 


REPORT CONNECT ABORT BUSY " ATDT5551212 CONNECT " ogin: account 
T his sequence expects nothing and then sends the string ATpT5551212 to dial the tdephone T he expected string is CONNECT. 


If the string Connect is received, the renainder of the script is executed. In addition, the program writes to the expect-file the 
string CONNECT plus any characters that follow it such as the connection rate. 


TIME-OUT 
The initial time-out value is 45 seconds. This may be changed using the -t parameter. 
To change the time-out value for the next expect string, the following example may be used: 
ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:-ogin: TIMEOUT 5 password:: hello2u2 
This changes the time-out to 1@ seconds when it expects the login: prompt. The time-out is then changed to 5 seconds 
when it looks for the password prompt. 
The timeout, once changed, remains in effect until it is changed again. 


SENDING EOT 


The special reply string of Eot indicates that the chat program should send an Eot character to the remote. T his is usually the 
End-of-file character sequence. A return character isnot sent following the cor. T he EoT sequence may be embedded into the 
send string using the sequence ~p. 


GENERATING BREAK 
The special reply string of BREAK Causes a break condition to be sent. T he break is a special signal on the transmitter. The 
normal processing on the receiver isto change the transmission rate. It may be used to cycle through the available transmis- 
sion rates on the remote until you are able to receive a valid login prompt. T he break sequence may be enbedded into the 
send string using the \k sequence 


ESCAPE SEQUENCES 


The expect and reply strings may contain escape sequences. All the sequences are legal in the reply string. M any are legal in 

the expect. T hose that are not valid in the expect sequence are so indicated. 

ms Expects or sends anull string. If you send anull string, it will still send the return 
character. T his sequence may athe be a pair of apostrophe or quote characters. 

\\b Represents a backspace character. 
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\\c 


\\d 


\\K 
\\n 
\\N 


\\p 
\\q 


\\r 
\\s 


\\t 
\\A\\ 
\\ddd 


“Cc 


TERMINATION CODES 


Suppresses the newline at the end of the reply string. This isthe only method to send a 
string without a trailing return character. It must be at the end of the send string. For 
example, the sequence he1lo\c will simply send the characters h, e, 1, 1, 0. (Not valid in 
expect.) 

D elay for onesecond. The program uses sleep(1), which will delay to amaximum of 
onesecond. (N ot valid in expect.) 

Insert a BREAK. (N ot valid in expect.) 

Send anewline or linefeed character. 

Send anull character. The same sequence may be represented by \o. (Not valid in 
expect.) 

Pause for a fraction of a second. T he delay is one tenth of a second. (N ot valid in 
expect.) 


its place. (N ot valid in expect.) 
Send or expect a carriage return. 


Represents a space character in the string. T hismay be used when it is not desirable to 
quote the strings that contains spaces. The sequenceHI TImand HI\sTIm are thesame 


Send or expect atab character. 

Send or expect abackslash character. 

Collapse the octal digits (dda) into a single ASCII character and send that character. 
(Some characters are not valid in expect.) 

Substitute the sequence with the control character represented by c. For example the 
character pc1 (17) isshown as *a. (Some characters are not valid in expect.) 


The chat program will terminate with the following completion codes: 


1) 


N DO oO Ff 


The normal termination of the program. This indicates that the script was executed 
without error to thenormal conclusion. 


Oneor more of the paramete’s are invalid or an expect string was too large for the 
internal buffers. T his indicates that the program as not properly executed. 


An error occurred during the execution of the program. This may be due to aread or 
write operation failing for some reason or chat recaving a signal such aS SIGINT. 


A time-out event occurred when there was an expect string without having a -subsend 
string. This may mean that you did not program the script correctly for the condition or 
that some unexpected event occurred and the expected string could not be found. 


The first string marked as an aBorT condition occurred. 

Thesecond string marked as an aBorT condition occurred. 

The third string marked as an aBorT condition occurred. 

The fourth string marked as an aBorT condition occurred. 

The other termination codes are also strings marked as an aBorT condition. 


Using the termination code, it is possible to determine which event terminated the script. It is possible to decide if the string 
BUSY was received from the modem as opposed to No DIAL Tone. Although thefirst event may be retried, the second will 
probably have little chance of succeeding during a retry. 


SEE ALSO 


Additional information about chat scripts may be found with UU CP documentation. T he chat script was taken from the 
ideas proposed by the scripts used by the uucico program. 


uucico(L), uucp(1) 


dock Ea 
COPYRIGHT 


The chat program isin public domain. This isnot theGN U public license If it breaks, then you get to keep both pieces. 
Chat Version 1.9,5 May1995 


chroot 


chroot— Change root directory and execute a program there. 


SYNOPSIS 


chroot directory program [ arg ... ] 


DESCRIPTION 


chroot changes the root directory for a process to a new directory executes a program there. 


SEE ALSO 


chroot(2) 


AUTHOR 


Rick Sladkey (jrs@world.std.com) 
Linux 0.99, 20 N ovanber 1993 


clock 


clock— M anipulate the CM OS clock. 
SYNOPSIS 


/sbin/clock [ 
/sbin/clock [ - 
/sbin/clock [ - 
/sbin/clock [ - 


DESCRIPTION 


clock manipulates the C M OS clock in various ways, allowing it to be read or written and allowing synchronization between 
the CMOS clock and the kernel’s version of the system time. 


ones 


OPTIONS 
-u Indicates that the CM OS clock is set to Universal Time 
-r Read CM OS clock and print the result to stdout. 
-w W rite the systen time into theCM OS clock. 
“8 Sé& the system time from theC M OS clock. 
-a Se the system time from theC M OS clock, adjusting the time to correct for systematic 


error and writing it back into theCM OS clock. T his option uses the file /etc/adjtime 
to determine how the clock changes. It contains three numbers. 


The first number is the correction in seconds per day. (For example, if your clock runs 5 
seconds fast each day, the first number should read -5.0.) 


The second number tells when clock was last used in seconds since 1/1/1970. 


The third number is the remaining part of a second that was leftover after the last 
adjustment. 
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The 


1. 
2. 


OVO BO) 


FILES 
/etc 


/etc 


AUTHO 
V1.0 
V1 
V1.2 
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following instructions are from the source code: 


Create afile /etc/adjtime containing asthe first and only lineo.o @ 0.9. 

Run clock -auOr clock -a, depending on whether your CM OS isin Universal or Local Time This updates the 
second number. 

Set your system time using the date command. 

Update yourCMOS timeusing clock -wuOrclock -w. 

Replace the first number in /etc/adjtime by your correction. 

Put thecommand clock -auOrclock -ain your /etc/rc.1local or let cron(8) start it regularly. 


/adjtime 
/rc.local 
RS 
Charles H edrick (hedrick@cs.rutgers.edu) Apr 1992 
M odified for clock adjustments, Rob H ooft (hoof t@chem. ruu.n1) Nov 1992 
Patches by H arald Koenig (koenig@nova.tat.physik.uni-tuebingen.de) applied by 


Rob H ooft (hoof t@EMBL -Heidelberg.DE) O ct 1993 


Linux 0.99, 24 D ecanber 1992 


comsat 


comsat— Biff server 


SYNOPSIS 


comsat 


DESCRIPTION 


comsat isthe server process that receives reports of incoming mail and notifies users if they requested this service comsat 
receives messages on a datagram port associated with the biff service specification (see services(5) and ineta(8)). Theone 
line messages are of the form 


user @mailbox-offset 


If the user specified is logged in to the system and the associated terminal has the owner execute bit turned on (by a biff y), 
the offset is used as a seek offset into the appropriate mailbox file and the first 7 lines or 560 characters of the message are 
printed on the use’’s terminal. Lines that appear to be part of the message header other than the From, To, Date, or Subject 


lines 


FILES 


are not included in the displayed message. 


/var/run/utmp to find out who's logged on and on what terminals 


SEE ALSO 


bitf(1), ineta(8) 


BUGS 


The message header filtering is prone to error. The density of the information presented is near the theoretical minimum. 
Users should be notified of mail that arrives on other machines than the oneto which they are currently logged in. 


The notification should appear in a separate window so it does not mess up the screen. 
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BSD 4.2, 16 March 1991 


HISTORY 
The command appeared in BSD 4.2. 


crond 


crond— cron daemon (Dillon’s Cron). 


SYNOPSIS 


crond [-l#] [-d[#]] [-f] [-b] [-c directory] 


OPTIONS 


crond isa background daemon that parses individual crontab files and executes commands on behalf of the users in 
question. 


-lloglevel Se logging level; default is 8. 
-d[debuglevel ] Sé& debugging leva; default is a. If no level is specified with the -a option, the default is 
1. This option also sets the logging level to and causes crond to run in the foreground. 
-f Run crond in the foreground. 
-b Run crond in the background (the default unless - a is specified). 
-c directory Specify directory containing crontab files. 
DESCRIPTION 


crond is responsible for scanning the crontab files and running their commands at the appropriate time The crontab 
program communicates with crond through the cron. update file, which residesin the crontabs directory, usually /var/ 
spool/cron/crontabs. T hisis accomplished by appending the filename of the modified or deleted crontab file to 
cron.update, which crond then picks up to resynchronize or renove its internal representation of the file. 


crond has anumber of built-in limitations to reduce the chance of it being ill-used. Potentially infinite loops during parsing 
are dealt with via a failsafe counter, and user crontabs are generally limited to 256 crontab entries. crontab lines may not 
be longer than 1024 characters, including the newline 


W henevet crond must run ajob, it first creates a daenon-owned temporary file o_Exct and o_APPEND to store any output, 
and then it fork()sand changes its user and group permissions to match that of the user the job is being run for. Then, it 
executes /bin/sh -c to run thejob. Thetemporary file renains under the ownership of the daemon to prevent the user from 
tampering with it. U pon job completion, crond verifies the secureness of the mail file and, if it has been appended to, mails 
to the file to user. The sendmail program isrun under theuser’s UID to prevent mail-related security holes. Unlike 
crontab, the crond program does not leave an open descriptor to the file for the duration of the job’s execution because this 
might cause crond to run out of descriptors. When the crontab program allows a user to edit his crontab, it copiesthe 
crontab to a use’-owned file before running the user's preferred editor. The suid crontab program keeps an open 
descriptor to the file which it later uses to copy the file back, thereby ensuring the user has not tampered with the file type 


crond always synchronizes to the top of the minute, checking the current time against the list of possiblejobs. T he list is 
stored such that the scan goes very quickly, and crond can deal with several thousand entries without taking any noticeable 
amount of CPU. 


AUTHOR 


M atthew D illon (dillon@apollo.west.oic.com) 
1 May 1994 


Part VIII: Administration and Privileged Commands 


ctlinnd 


ctlinnd— Control the InterN aN ews daenon. 


SYNOPSIS 


linnd [ -h ][-s ][-t timeout ] command [ argument... ] 


DESCRIPTION 


ctlinnd sends a message to the control channd of inna(8), the Inte-N e&tN ews server. 


ro} 


In the normal mode of behavior, the message is sent to the server, which then performs the requested action and sends back a 
eply with a text message and the exit code for ct1inna. If the server successfully performed the command, ct1innd will exit 
with a status of zero and print the reply on standard output. If the server could not perform the command (for example it 
was told to remove a newsgroup that does not exist), it will direct ct1innd to exit with a status of one. The shutdown, 
xabort, and xexec commands do not generate a reply; ctlinnd will always exit silently with a status of zero. If the -s flag is 
used, then no message will be printed if the command was successful. 


= 





The -+ flag can be used to specify how long to wait for the reply from the server. The timeout value specifies the number of 
seconds to wait. A value of zero waits forever, and a value less than zero indicates that no reply is needed. When waiting for a 
reply, ctlinnd will try every two minutes to see if the server is still running, so it is unlikely that -to will hang. The default 
iS-to 


To seea command summary, use the -h flag. If acommand isincluded when ctlinnd isinvoked with the -h flag, then only 
the usage for that command will be given. 


If alarge number of groups are going to be created or ddeted at once, it may be more efficient to pause or throttle the server 
and edit the active file directly. 


The complete list of commands follows. N ote that all commands have a fixed number of arguments. If a parameter can be an 
empty string, then it is necessary to specify it as two adjacent quotes (""). 


addhistMessage-| Darr exp post paths Add an entry to the history database T his directs the server to createa 
history line for M essage-|D . The angle brackets are optional. arr, exp, and 
post Specify when the article arrived, what its expiration date is, and when it 
was posted. All three values are a number indicating the number of seconds 
since the epoch. If the article does not have an Expires header, then exp 
should be zero. paths isthe pathname within the newsspool directory where 
the article is filed. If the article is cross-posted, then the names should be 
separated by whitespace and the paths argument should be inside double 
quotes. If the server is paused or throttled, this command causes it to briefly 
open the history database 


allow reason Remote connections are allowed. T he reason must be the same text given 
with an earlier reject command or an empty string. 
begin site Begin feeding site. This will cause the server to rescan the newsfeeds(5) file 


to find the specified site and set up a newsfeed for it. If the site already exists, 
a “drop” isdonefirst. T his command is forwarded; see below. 

cancel <Message-|D> Remove the article with the specified M essage-ID from the local system. This 
does not generate a cancel message. T he angle brackets are optional. If the 
server is paused or throttled, this command causes it to briefly open the 
history database. 

changegroup group rest The newsgroup group is changed so that its fourth field in the active file 
becomes the value specified by the rest parameter. T his may be used to make 
an existing group moderated or unmoderated, for example. 

checkfile Check the syntax of the newsfeeds file, and display a message if any errors are 
found. T he details of the errors are reported to syslog(3). 


drop site 


flush site 


flushlogs 


go reason 


hangup channel 


help [command ] 


mode 


name nnn 


newgroup group rest creator 


param letter value 


pause reason 


readers flag text 
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Flush and drop site from the server's list of active feeds. This command is 
forwarded; see below. 

Flush the buffer for the specified si te. The actions taken depend on the type 
of feed the site receives; see newsfeeds(5). This is useful when the site is fed 
by afile and batching is going to start. If siteis an empty string, then all sites 
are flushed and the active file and history databases are also written out. This 
command is forwarded; see below. 


Close the log and error log files and rename them to havea .o1a extension. 
The history database and active file are also written out. 


Reopen the history database and start accepting articles after a pause or 
throttle command. Thereason must either be an empty string or match the 
text that was given in the earlier pause or throttle command. If a rgect 
command was done, this will also do an allow command if the reason 
matches the text that was given in the r@ect. If a reserve command was done, 
this will also clear the reservation if the reason matches the text that was given 
in the reserve. N ote that if only the history database has changed while the 
server is paused or throttled, it is not necessary to send it areload command 
before sending it ago command. If the server throttled itself because it 
accumulated too many |/O errors, this command will reset the error count. If 
the server was not started with the -ny flag, then thiscommand also does a 
readers command with yes asthe flag and reason asthe text. 


Close the socket on the specified incoming channel . Thisis useful when an 
incoming connection appears to be hung. 


Print acommand summary for all commands, or just command if specified. 


Print the server's operating mode asa multiline summary of the parameters 
and operating state. 

Print the name of channd number nnn or of all channas if it isan enpty 
string. 

Create the specified newsgroup. Therest parameter should be the fourth 
fidd as described in active(5); if it isnot an equal sign, only the first letter is 
used. Thecreator should be the name of the person creating the group. If the 
newsgroup already exists, this is equivalent to the changegroup command. 
Thisis the only command that has defaults. T he creator can be omitted and 
will default to the empty string, and therest parameter can be omitted and 
will default to y. T his command can be done while the server is paused or 
throttled; it will update its internal state when a go command is sent. This 
command updates the active. times (See active(5)) file 

Change the command-line parameters of the server. The combination of 
defaults makes it possible to use the text of the Control header directly. 
letter isthe innd command-line option to set, and val ue isthe new value. 
For example, i 5 directs the server to allow only five incoming connections. 
To enable or disable the action of the -n flag, use the letter y or n for the 
value. 

Pausethe server so that no incoming articles are accepted. N o existing 
connections are closed, but the history database is closed. T his command 
should be used for short-term locks, such as when replacing the history files. 
If the server was not started with the -ny flag, then this command also does a 
readers command with no as the flag and reason asthe text. 

Allow or disallow newsreaders. If fag starts with the letter n, then 
newsreading is disallowed by causing the server to pass the text as the value of 
the nnrpd(8) -r flag. If f1 ag starts with the letter y and text is either an empty 
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reject reason 


reload what reason 


renumber group 


reserve reason 


rmgroup group 


send feed text... 


shutdown reason 


signal sig site 


throttle reason 


trace item flag 


xabort reason 


xexec path 


string, or the same string that was used when newsreading was disallowed, 
then newsreading will be allowed. 

Remote connections (those that would not be handed off to nnrpd) are 
rejected, with reason given as the explanation. 

The server updates its in-memory copies of various configuration files. what 
identifies what should be rdoaded. If it isan empty string or the word a11, 
then everything is rdoaded; if it isthe word history, then thehistory 
database is closed and opened; if it is the word hosts.nntp, then the 

hosts .nntp(5) file is reloaded; if it isthe word active Or newsfeeds, then 
both the active and newsfeeds files are reloaded; if it istheword 

overview. fmt, then the overview. fmt(5) fileis reloaded. Thereason iS 
reported to syslog. T heveis no way to reload the data inn. conf(5) file the 
server currently only uses the pathhost parameter, so this restriction should 
not bea problem. 

Scan the spool directory for the specified newsgroup and update the low- 
water mark in the active file If group is an enpty string, then all newsgroups 
are scanned. 

The next pause or throttle command must usereason aSits text. This 
reservation is cleared by giving an empty string for ther eason. This 
command is used by programs such as expire(8) that want to avoid running 
into other instances of each other. 

Remove the specified newsgroup. T his is done by editing the active file. The 
spool directory is not touched, and any articles in the group will be expired 
using the default expiration parameters. U nlike the newgroup command, this 
command does not update the active. times file. 

The specified t ext issent as acontrol line to the explode feed. 


The server isshut down, with the specified reason recorded in the log and 
sent to all open connections. It is a good idea to send a throttle command 
first. 

Signal sig is sent to the specified site, which must bea channel or exploder 
feed. si g can be anumevic signal number or the word hup, int, Or term; case 
isnot significant. 

Input is throttled so that all existing connections are closed and new 
connections are rejected. T he history database is closed. T his should be used 
for long-term locks, such as when expire is being run. If the server was not 
started with the -ny flag, then this command also does a readers command 
with no asthe flag and reason asthe text. 

Tracing is turned on or off for the specified item. f! ag should start with the 
letter y or n to turn tracing on or off. If i tem starts as anumber, then tracing 
is set for the specified inna channa, which must be for an incoming N NTP 
feed. If it starts with the letter 1, then general innd tracing is turned on or off. 
If it starts with the letter n, then future nnrpa’s will or will not have the -+t 
flag enabled, as appropriate 

The server logs the specified reason and then invokes the abort(3) routine 
The server gets ready to shut itself down, but instead of exiting, it executes 
the specified path with all of its original arguments. If path is innd, then / 
news /bin/innd is invoked; if it isinndstart, then /news/bin/inndstart iS 
invoked; if it isan empty string, it will invoke the appropriate program 
depending on whether it was started with the -p flag; any other value is an 
error. 
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In addition to bang acted upon within the server, certain commands can be forwarded to the appropriate child process. If 
the site receiving the command is an exploder (such as buffchan(8)) or it isa funnel that feeds into an exploder, then the 
command can be forwarded. In this case, the server will send acommand line to the exploder that consists of the ctlinnd 
command name. If the site funnels into an exploder that has an asterisk (*) in its w flag (see newsfeea(5)), then the site name 
is appended to the command; otherwise, no argument is appended. 


BUGS 


etlinnd uses the inndcomn(3) library and istherefore limited to server replies no larger than 4KB. 


HISTORY 


Written by Rich $alz (rsalzeuunet .uu.net) for InterN &tN ews. 


SEE ALSO 


active(5), expire(8), innd(8), inndcomm(3), inn.cont(5), newsteeds(5), overview. fmt(5) 


ctrlaltdel 


ctrlaltdel— Se the function of the Ctrl+Alt4D el combination. 


SYNOPSIS 


ctrlaltdel hard{soft 


DESCRIPTION 


Based on examination of the 1inux/kernel/sys.c code, it is clear that there are two supported functions that the 
Ctrl+Alt+D d@ sequence can perform: a hard reset, which immediately reboots the computer without calling sync(2) and 
without any other preparation, and a soft reset, which sends the siaintT (interrupt) signal to the init process (this is always 
the process with PID 1). If this option is used, the init(8) program must support this feature. Because there are now several 
init(8) programsin the Linux community, consult the documentation for the version that you are currently using. 


ctrlaltdel is usually used in the /etc/rc.1ocal file 


FILES 


/etc/rc.local 


SEE ALSO 


simpleinit(8), init(8) 


AUTHOR 


Peter O rbaek (poe@daimi. aau. dk) 
Linux 0.99, 25 October 1993 


cvsbug 


evsbug— Send problem report (PR) about CVS to acentral support site. 


SYNOPSIS 


cvsbug [ site ][-f problemreport ][-t mail-address ][-P ][-L ] 
[--request-id ][-v ] 
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DESCRIPTION 


evsbug isa tool used to submit problem reports (PRs) to acentral support site In most cases, the correct site will be the 
default. This argument indicates the support site that is responsible for the category of problem involved. Some sites may use 
a local address as a default. Site values are defined by using the aliases(5). 


evsbug invokes an editor on a problem report template (after trying to fill in some fidds with reasonable default values). 
When you exit the editor, cvsbug sends the completed form to the Problem Report M anagement System (GNATS) ata 
central support site. At the support site, the PR is assigned a unique number and isstored in the GN ATS database according 
to its category and submitter 1D. GN ATS automatically replies with an acknowledgment, citing the category and the PR 
number. 


To ensure that a PR ishandled promptly, it should contain your (unique) submitter 1D and one of the available categories to 
identify the problem area. (Use cvsbug -L to seealist of categories.) 


The cvsbug template at your site should already be customized with your submitter ID (running install-sid submitter-id 
to accomplish thisis part of the installation procedures for cvsbug). If this hasn't been done, see your systen administrator 
for your submitter ID, or request one from your support site by invoking cvsbug — -request-id. If your site does not 
distinguish between different user sites, or if you are not affiliated with the support site, use net for this fidd. 


The more precise your problem description and the more complete your information, the faster your support team can solve 
your problans. 


OPTIONS 

-f problem report Specify a file (problem-report) that already contains a complete problem report. cvsbug 
sends the contents of the file without invoking the editor. If the value for prob! em-report 
is-, then cvsbug reads from standard input. 

-t mail-address Change mail address at the support site for problem reports. The default mai!- address is 
the address used for the default site U se the site argument rather than this option in 
nearly all cases. 

-P Print the form specified by the environment variablerr Form on standard output. If pr 
ForM is not set, print the standard blank PR template. No mail issent. 

“L Print the list of available categories. N o mail is sent. 

--request-id Sends mail to the default support site, or site if specified, with a request for your 
submitter ID . If you are not affiliated with site, usea submitter ID of net. 

“Vv Display the cvsbug version number. 


N ote: Use cvsbug to submit problem reports rather than mail then directly. U sing both the template and cvsbug itself will 
hdp ensure all necessary information will reach the support site. 


ENVIRONMENT 
The environment variable EptTor specifies the editor to invoke on the template. T he default is vi. 
If the environment variable pR Form isset, then its value is used as the filename of the template for your problen-report 


editing session. You can use this to start with a partially completed form (for example, a form with the identification fidds 
already completed). 


HOW TO FILL OUT A PROBLEM REPO RT 


Problem reports have to bein a particular form so that a program can easily manage them. Please remenber the following 
guidelines: 
Describe only one problem with each problem report. 


For follow-up mail, use the same subject line as the onein the automatic acknowledgment. It consists of category, PR 
number, and the original synopsis line T his allows the support site to rdate several mail messages to a particular PR and 
to record then automatically. 


cvtbatch 
Please try to be as accurate as possible in the subject or synopsis line. 


The subject and the synopsisline are not confidential. Thisis because open-bugs lists are compiled from them. Avoid 
putting confidential information there 


See theGN U Info file cvsbug. info or the document Reporting Problems W ith cvsbug for detailed information on reporting 
problems 


HOW TO SUBMIT TEST CASES, CODE, AND SO ON 


Submit small code samples with the PR. Contact the support site for instructions on submitting larger test cases and 
problematic source code. 


FILES 
/tmp/p$$ Copy of PR used in editing session 
/tmp/pf$$ copy of enpty PR form, for testing purposes 
/tmp/pbad$¢ file for rejected PRs 


EMACS USER INTERFACE 


An EMACS user interface for cvsbug with completion of fidd values is part of the cvsbug distribution (invoked with m-x 
cvsbug). See the file cvsbug. info or the ASCII file INSTALL in the top-leve directory of the distribution for configuration 
and installation information. The EM ACS LISP template file is cvsbug-e1. in and is installed as cvsbug.e1. 


INSTALLATION AND CONFIGURATION 


See cvsbug. info or INSTALL for installation instructions. 


SEE ALSO 
Reporting Problems U sing cvsbug (also installed as the GN U Info file cvsbug. info). 
gnats(l), query-pr(1), edit-pr(1), gnats(8), queue-pr(8), at-pr(8), mkcat(8), mkdist(8) 
AUTHORS 
J efrey Osier, Brendan K ehoe Jason M arrill, Heinz G. Seidl (Cygnus Support). 


COPYING 


Copyright(c) 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of 
this manual provided the copyright notice and this permission notice are preserved on all copies. 


Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Permission is granted to copy and distribute translations of this manual into another language under the above conditions 
for modified versions, except that this permission noticemay be included in translations approved by the Free Software 
Foundation instead of in the original English. 


XVERSION x, February 1993 


cvtbatch 


cvtbatch— Convert Usenet batch file to INN format. 


SYNOPSIS 


cvtbatch [ -witems ] 
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DESCRIPTION 


cvtbatch reads standard input as a series of lines, converts each line, and writes it to standard output. It is used to convert 
simple batchfiles that contain just the articlename to IN N batchfiles that contain additional information about each article 


Each line is taken as the pathname to a Useet article. If it is not an absolute pathname, it is taken rdative to the spool 
directory, /news/spool. (Only the first word of each line is parsed; anything following whitespace is ignored.) 


The -w flag specifies how each output line should be written. The items for this flag should be chosen from thew flag items 
as specified in newsfeeds(5). They may be chosen from the following set: 


b Size of article in bytes 

f Full pathname of article 

m Article M essage-| D 

n Relative pathname of article 


If the input file consists of a series of M essage-ID s, then use grephistory(1) with the -s flag piped into cvtbatch. 


HISTORY 


Written by Rich $alz (rsalzeuunet .uu.net) for InterN &tN ews. 


SEE ALSO 


grephistory(1) newsfeeds(5) 


cytune— T une C yclades driver parameters. 
SYNOPSIS 

cytune [-q [-iinterval ]] ([-s value]|[-S value]) 

[-g/G] ([-t timeout ]|[-T timeout ]) tty [tty ...] 
DESCRIPTION 


cytune queries and modifies the interruption threshold for the C yclades driver. Each serial line on aC yclades card has a 12- 
byte FIFO for input (and another 12-byte FIFO for output). The “threshold” specifies how many input characters must be 
present in the FIFO before an interruption is raised. When a Cyclades tty is opened, thisthreshold is set to a default value 





based on baud rate 

Baud Threshold 
50-4800 10 

9600 8 

19200 4 

38400 2 
57600-150000 1 


If the threshold is set too low, the large number of interruptions can load the machine and decrease overall systen through- 
put. If the threshold is set too high, the FIFO buffer can overflow, and characters will be lost. Slower machines, however, 
may not be able to deal with the interrupt load and will require that the threshold be adjusted upwards. 


If the Cyclades driver was compiled with ENABLE MONITORING defined, the cytune command can be used with the -q option 
to report interrupts over the monitoring interval and characters transferred over the monitoring interval. It will also report 


the state of the FIFO. Themaximum number of charactersin the FIFO when an interrupt occurred, the instantaneous 
count of characters in the FIFO, and how many characters are now in theFIFO are reported. This output might look like 
this: 

/dev/cubC@: 830 ints, 9130 chars; fifo: 11 threshold, 11 max, 11 now 

166.259866 interrupts/second, 1828.858521 characters/second 


This output indicates that for this monitoring period, the interrupts were always being handled within onecharacter time 
because max never rose above threshold. T hisis good, and you can probably run this way, provided that alarge number of 
samples come out this way. You will lose characters if you overrun the FIFO because the C yclades hardware does not seam to 
support the RT S RS-232 signal line for hardware flow control from the DCE to theDTE. 


cytune will in query mode produce a summary report when ended with a sta@rnT or when the threshold or time-out is 
changed. 


There may be a responsiveness versus throughput tradeoff. T he C yclades card, at the higher speeds, is capable of putting a 
very high interrupt load on the system. T his will reduce the amount of CPU time available for other tasks on your system. 

H owever, the time it takes to respond to a single character may be increased if you increase the threshold. This might be 
noticed by monitoring ping(8) times on aSLIP link controlled by aC yclades card. If your SLIP link is generally used for 
interactive work such aSte1net(1), you might want to leave the threshold low so that characters are responded to as quickly 
as possible. If your SLIP link is generally used for file transfer, WWW, and thelike setting the FIFO to ahigh valueis likely 
to reduce the load on your system while not significantly affecting throughput. Alternatively, see the -t or -T optionsto 
adjust the time that the Cyclades waits before flushing its buffer. U nits are 5ms. 


If you are running amouse on aC yclades port, it is likely that you want to maintain the threshold and time-out at alow 
value. 


OPTIONS 


-S value Set the current threshold to value characters. N ote that if the tty isnot being had open 
by another process, the threshold will be reset on the next open. O nly values between 1 
and 12, inclusive, are permitted. 

-t value Set the current flush timeout to val ve units. N ote that if thetty isnot being hdd open 
by another process, the threshold will be reset on the next open. O nly values between 
and 255, inclusive, are permitted. Setting value to @ forces the default, currently ox20 
(160ms) but soon to be exe2 (10ms). U nits are 5ms. 

-g Get the current threshold and time-out. 

-T value Sé& the default flush time-out to val ue units. When the tty is next opened, this value is 
used instead of the default. If value is a, then the value defaults to ax20 (160ms), soon to 
be exo2 (10ms). 


-G Get the default threshold and flush time-out values. 
-q Gather statistics about the tty. T he results are only valid if the C yclades driver has been 
compiled with ENABLE MONITORING defined. Thisis probably not the default. 
-i interval Statistics will be gathered every interval seconds. 
BUGS 


If you run two copies of cytune at the sametime to report statistics about the same port, the ints, chars, and max values will 
be reset and not reported correctly. cytune(8) should prevent this but does not. 


AUTHOR 


Nick Simicich (njs@scifi.emi.net), with modifications by Rik Faith (faith@cs.unc. edu) 
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FILES 
/dev/ttyC[0-8] 
/dev/cubC[0-8] 


SEE ALSO 


setserial(8) 
4 March 1995 


debugfs 


debugfs— ext2 filesysten debugger. 


SYNOPSIS 


debugfs [[-w ]device] 


DESCRIPTION 


debugfs isa filesystem debugger. It can be used to examine and change the state of an ext2 filesystem. device isthe special 
file corresponding to the device containing the ext2 filesystem (such as /dev/hdxx). 


OPTIONS 
-W Specify that the filesystan should be open in read-write mode W ithout this option, 
the filesystem is open in read-only mode. 
COMMANDS 
debugfs isan interactive debugger. It understands a number of commands: 
ed file 
chroot file 
close Close the currently open filesystem. 
clri file Clear the contents of the inode corresponding to tile. 
expand_dir, file Expand a directory. 
find_free block [goal ] Find the first free block, starting from goa! , and allocate it. 
find free inode [dir [mode]] Find a free inode and allocateit. 
freeb block M ark the block as not allocated. 
freei file Free the inode corresponding to file. 
help 
iname inode Print the filevame corresponding toi node (currently not implemented). 
initialize device blocksize Create an ext2 file systen on device. 
kill file file Remove a file and deallocate its blocks. 
In source file dest_file Create a link. 
1s [pathname ] Emulate the 1s(1) command. 
Modify_inode file M odify the contents of the inode corresponding to file. 
mkdir file M ake a directory. 
open [-w] device Ope a filesystem. 
pwd 


quit Quit debugfs. 


dip 


rm file Remove afile 
rmdir file Remove a directory. 
setb block M ark the block as allocated. 
seti file M ark in use the inode corresponding to file 
show_super_stats List the contents of the super block. 
stat file Dump the contents of the inode corresponding to file. 
testb block T est if the block is marked as allocated. 
testi file Test if the inode corresponding to file ismarked as allocated. 
unlink file Remove alink. 
AUTHOR 
debugfs was written by Theodore T 'so (tytso@mit.edu). 
SEE ALSO 


dumpe2fs(8), e2fsck(8), mke2fs(8) 
Vergon 0.5b, N ovenber 1994 


dip 
dip— D ialup IP connection handler. 


SYNOPSIS 


dip [-t] 
dip [-ktv] [-m mtu] scriptfile 
dip [-iv] [user_name] 


DESCRIPTION 
dip handles the connections needed for dialup IP links, such as SLIP or PPP. It can handle both incoming and outgoing 
connections, using password security for incoming connections. T he outgoing connections use the system’s dia1(3) library 
if available. 


COMMAND MODE 
The first possible use of dip is as a stand-alone program to set up an outgoing IP connection. This can be done by invoking 
dip with the -t option, which means ante Test mode and, more precisay, dump you in the commanD - move of the dip 
program. You are raninded of this by the prP> prompt, or, if you also specified the -v debugging flag, the p1P [NNNN]> 
prompt. The latter prompt also displays the current value of the global erriv1 variable which is used mostly when dip runs 
in script mode. For the interactive mode, it can be used to determineif the result of the previous command was okay. 


The following isa sample taken from a live session: 


$dip-t 
DIP: Dialup IP Protocol Driver version 3.3.7 (12/13/93) 
Written by Fred N. van Kempen, MicroWalt Corporation. 


DIP>_ 


The most hapful command in this modeis, of course, the help command, which should produce an output similar to this: 


DIP> help 
DIP knows about the following commands: 
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databits default dial echo flush 
get goto help if init 

mode modem parity print port 
reset send sleep speed stopbits 
term wait 


DIP>_ 


All commands display how they should be used when invoking then with no or invalid arguments. J ust experiment alittle to 
get the feel of it, and havea look at the sample script files, which also use this command language. 


DIALIN MODE 


The second possible way of using dip isasalogin shal for incoming IP connections, asin dialup SLIP and PPP connections. 
To make integration into the existing UNIX system as easy as possible, dip can be installed as imply as using it as a login 
shell in the system's password file A sample entry lookslike 


suunet: ij /SMxiT1GVCo:1004:10:UUNET:/tmp:/usr/bin/dip -i 


When user suunet logs in, the login(1) program sets the home directory to /tmp and execute the dip program with the -i 
option, which means that dip must run in input mode dip then triesto locate the name of the logged-in user (the name 
corresponding to its current user ID, as returned by the getuid(2) system call) in its database file An optional single 
argument to the dip program in thismode can be the username that must be used in this lookup, regardless of the current 
user ID. 


dip now scans the /etc/net/diphosts file for an entry for the given username. T his file contains lines of text (much like the 
standard password file). The format looks like 


diphosts This file describes a number of name to 
address mappings for the DIP program. It 

is used to determine which IP address to 

use for in incoming call of some user. 


Version: @(#)diphosts 1.00 12/10/92 FvK 


Author: Fred N. van Kempen, 
<waltje@uwalt.nl.mugnet.org> 


HH Ht HH HH HH HK 


suunet: :uunet.uu.net:UUNET SLIP:SLIP,296 


# End of diphosts. 


The first field of a line identifies the username, which you must match. The second field can contain an encrypted password. 
If this field is non-null, thedip program asks for an external security password, which must match the password in this field. 
The third fidd contains the name (or raw IP address) of the host that is connecting to the system with this link. If a 
hostname is given, the usual address resolving process is started, using either anameserver or a local hosts file. 


The fourth field can contain any text; it is not (yet) used by the dip program. In future releases, this info may be used in the 
system log files. Finally, the fifth field of a line contains a mixture of comma-separated flags. Possible flags are 

sLtp to indicate you must use the SLIP protocol. 

ppp to indicate you must use the PPP protocol. 

number, which givesthe MTU parameter of this connection. 
After finding the correct line, dip puts the terminal line into RAW mode and asks the system networking layer to allocate a 


channel of the desired protocol. Finally, if the channel is activated, it adds an entry to the systan’s routing table to make the 
connection work. 


dip now goes into an endless loop of sleeping, which continues until the connection is physically aborted (the line is 
dropped). At that time, dip removes the entry it made in the system’s routing table and releases the protocol channd for 
reuse. It then exits, making room for another session. 


DIALOUT MODE 


The last way of using dip is as a program that initiates outgoing connections. To make life easier for the people who have to 
manage links of this type, dip uses a chat script to set up alink to a remote systan. T his gives the user an enormous amount 
of flexibility when making the connection, which otherwise could require many command-line options. The pathname of 
the script to be run is then given as the single argument to dip; the program will automatically check if the file has a filename 
ending in a .dip part. This isnot mandatory— just atool to group scripts together in a single directory. A script should look 
something like this: 


sample.dip Dialup IP connection support program. 
This file (should show) shows how to use the DIP 
scripting commands to establish a link to a host. 
This host runs the 386bsd operating system, and 

thus can only be used for the "static" addresses. 


NOTE: We also need an examnple of a script used to 
connect to a "dynamic" SLIP server, like an Annex 
terminal server... 


Version: @(#)sample.dip 1.30 07/05/93 


Author: Fred N. van Kempen, <waltje@uWalt.NL.Mugnet.ORG> 


H+ +t HHH HH HH HH HH HK HK 


main: 

# First of all, set up our name for this connection. 
# I am called "“uwalt.hacktic.nl" (== 193.78.33.238) 
get $local uwalt.hacktic.nl 

# Next, set up the other side's name and address. 
# My dialin machine is called 'xs4all.hacktic.nl' (== 193.78.33.42) 
get $remote xs4all.hacktic.nl 

# Set the desired serial port and speed. 

port cuad 

speed 38400 

# Reset the modem and terminal line. 

# This seems to cause trouble for some people! 
reset 

# Prepare for dialing. 

send ATQOV1E1X1 

wait OK 2 

if $errlvl != 0 goto error 

dial 555-1234567 

if $errlvl != 0 goto error 

wait CONNECT 60 

if $errlvl != 0 goto error 

# We are connected. Login to the system. 

login: 

sleep 3 

send \r\n\r\n 

wait ogin: 10 

if $errlvl != 0 goto error 

send NO-WAY\n 

wait ord: 5 

if $errlvl != 0 goto error 

send HA-HA\n 
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wait $ 30 

if $errlvl != 0 goto error 
loggedin: 
# We are now logged in. Start the ‘sliplogin' program, 

# as this is not automatically done for me. 

send sliplogin\n 

wait SOME-STRING 15 

# Set up the SLIP operating parameters. 

get $mtu 1500 

# Set Destination net/address as type ‘default' (vice an address). 

# This is used by the 'route' command to set the kernel routing table. 
# Some machines seem to require this be done for SLIP to work properly. 
default 
# Say hello and fire up! 

done: 

print CONNECTED to $remote with address $rmtip 
mode SLIP 

goto exit 

error: 

print SLIP to $remote failed. 

exit: 





This script causes dip to dial up ahost, login, and g& a SLIP interface channd going (in the same manner as with incoming 
connections). When all is set up, it simply goes into the background and waits for a hangup (or just a lethal signal), at which 
it hangs up and exits. 


FILES 
/etc/passwd 


/etc/diphosts 


AUTHORS 


Fred N. van Kempen (walt je@uwalt.n1.mugnet.org), Paul M ossip (mossip@vizlab.rutgers.edu), J eff U phoff 
(juphoff@aoc.nrao.edu), Jim Seagrave (j es@grendel.demon.co.uk), Olaf Kirch (okir@monad.sub.de). 


Verson 3.3.7, 13 December 1993 


dmesg 


dmesg— Print or control the kernal ring buffer. 


SYNOPSIS 


dmesg [ -c ] [ -nlevel ] 


DESCRIPTION 
dmesg iS used to examine or control the kernd ring buffer. 
The program helps users to print their bootup messages. Instead of copying the messages by hand, the user need only 


dmesg > boot.messages 


and mail the boot .messages file to whoever can debug thar problem. 


e2fsck 


OPTIONS 
-c Clear thering buffer contents after printing. 
-n level Sé theleva at which logging of messages is done to the console For example -n 1 


prevents all messages, except panic messages, from appearing on the console All 
levels of messages are still written to /proc/kmsg, SO sysloga(8) can still be used to 
control exactly where kernd messages appear. When the -n option is used, dmesg 
will not print or clear the kernel ring buffer. 


W hen both options are used, only the last option on the command line will have an effect. 


SEE ALSO 


syslogd(8) 


AUTHOR 


TheodoreT s'0 (tytso@athena.mit.edu) 
Linux 0.99, 28 October 1993 


dumpe2ts 


dumpe2fs— D ump filesystem information. 


SYNOPSIS 


dumpe2fs device 


DESCRIPTION 
dumpe2fs prints the super block and blocks group information for the filesystem present on device. 
dumpe2fs is similar to Berkeley's dumpfs program for the BSD Fast File System. 


BUGS 
You need to know the physical filesystem structure to understand the output. 


AUTHOR 


dumpe2fs was written by Reny Card (card@masi.ibp.fr), the devdoper and maintaine of the ext2 fs. 


AVAILABILITY 


dumpe2fs is available for anonymous FT P from ftp.ibp.fr and tsx-11.mit.edu iN /pub/linux/packages/ext2fs. 


SEE ALSO 
e2fsck(8), mke2fs(8), tune2fs(8) 
Vergon 0.5b, N ovenber 1994 


e2f sck 


e2fsck— Check a Linux second extended filesystem. 


SYNOPSIS 


e2fsck [ -panyrdfvtFV ][-b superblock ][-B blocksize ] 
[-1}-L bad_blocks_ file ] device 
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DESCRIPTION 


e2fsck iSused to check a Linux second extended file system. 


device 


OPTIONS 


a 
-b superblock 


-B blocksize 


-1 filename 


-L filename 


EXIT CODE 


The special file corresponding to the device (such as /dev/hdxXx). 


This option does the same thing as the -p option. It is provided for backwards 
compatibility only; it is suggested that people use -p option whenever possible. 
Instead of using the normal superblock, use the alternative superblock specified by 
superblock. 

Usually, e2fsck will search for the superblock at various different block sizes in an 
attempt to find the appropriate block size. T his search can be fooled in some cases. 
This option forces e2fsck to only try locating the superblock at a particular 
blocksize. If the superblock is not found, e2fsck will terminate with a fatal error. 
Print debugging output (useless unless you are debugging e2fsck ). 

Force checking even if the filesystem seems clean. 

Flush the filesystem device's buffer caches before beginning. O nly really useful for 
doing e2fsck time trials. 

Add the blocks listed in the file specified by filerame to thelist of bad blocks. 

Sé& the bad blocks list to be the list of blocks specified by fi! ename. (This option is 
the same as the -1 option except the bad blocks list is cleared before the blocks listed 
in thefile are added to the bad blocks list.) 

Open the filesystem read-only, and assume an answer of “no” to all questions. 
Allows e2fsck to be used non-interactively. (N ote: if the -1 or -L options are 
specified in addition to the -n option, then the filesysten will be opened read-write 
to permit the bad-blocks list to be updated. H owever, no other changes will be made 
to the filesystem.) 

Automatically repair (“preen”) the filesystem without any questions. 

This option does nothing at all; it is provided only for backwards compatibility. 
Print timing statistics for e2tsck. If this option is used twice additional timing 
statistics are printed on a pass-by-pass basis. 

Verbose mode. 

Print version information and exit. 

Assume an answer of “yes” to all questions; allows e2fsck to be used non- 
interactively. 


The exit code returned by e2fsck isthe sum of the following conditions: 


0 
1 
2 
4 
8 


16 
128 


No errors 

Filesystem errors corrected 

Filesystem errors corrected; systen should be rebooted if filesystem was mounted 
Filesystem errors left uncorrected 

O perational error 

Usage or syntax error 

Shared library error 


edquota 
BUGS 


Almost any piece of software will have bugs. If you manage to find a filesystem that causes e2fsck to crash, or that e2fsck is 
unable to repair, please report it to the author. 


Please include as much information as possible in your bug report. Ideally, include a complete transcript of the e2fsck run, 
so | can see exactly what error messages are displayed. If you have a writeable filesystem where the transcript can be stored, 
the script(1) program isa handy way to save the output of e2fsck to afile 


It is also useful to send the output of dumpe2ts(8). If a specific inode or inodes seams to be giving e2fsck trouble, try 
running the debugfs(8) command and send the output of the stat command run on the relevant inodes. If theinodeisa 
directory, the debugfs dump command will allow you to extract the contents of the directory inode, which can sent to me 
after being first run through uuencode(1). 


Always include the full version string that e2tsck displays when it is run so | know which version you are running. 


AUTHOR 


This version of e2fsck is written by TheodoreT so (tytso@mit. edu). 


SEE ALSO 
mke2fs(8), tune2fs(8), dumpe2fs(8), debugts(8) 
Vergon 0.5b, N ovenber 1994 


edquota— Edit user quotas. 

SYNOPSIS 
/usr/etc/edquota [ -p proto-user ][-ug ] name... 
/usr/etc/edquota [ -ug ] -t 

DESCRIPTION 


edquota is a quota editor. One or more users or groups may be specified on the command line For each user or group, a 
temporary file is created with an ASCII representation of the current disk quotas for that user or group and an editor isthen 
invoked on the file T he quotas may then be modified, new quotas added, and so on. U pon leaving the editor, edquota reads 
the temporary file and modifies the binary quota files to reflect the changes made. 


The editor invoked is vi(1) unless the environment variable specifies otherwise. 


Only the superuser may edit quotas. (For quotas to be established on afilesystem, the root directory of the filesystem must 
contain afile owned by root, called quota.user OF quota.group. See quotaon(8) for details.) 


OPTIONS 
-u Edit the userquota. T his is the default. 
-g Edit the groupquota. 
-p D uplicate the quotas of the prototypical user specified for each user specified. This is 
the normal mechanism used to initialize quotas for groups of users. 
-t Edit the soft time limits for each filesystem. If the time limits are zero, the default 


time limits in <1inux/quota.h> are used. Time units of sec(onds), min(utes), 
hour(s), day(s), week(s), and month(s) are understood. Time limits are printed in the 
greatest possible time unit such that the value is greater than or equal to one 
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FILES 

quota.user OF quota.group Quota file at the filesystem root 

/etc/mtab M ounted filesystems 
SEE ALSO 

quota(1), vi(1), quotact1(2), quotacheck(8), quotaon(8), repquota(8) 
BUGS 

The format of the temporary file is inscrutable 

8 June1993 

expire 

expire—Usmet article and history expiration program. 
SYNOPSIS 

expire [ -d dir ][-f file ][-g file ][-hfile ] 

[-i ][-1 ][-n ]f-p ][-q ][-r reason ][-s ][-t ] 

[-v level ][-w number ][-x ][-z file ][expire.ct1l] 
DESCRIPTION 


expire scans the history(5) text file /news/1ib/history and uses the information recorded in it to purge old news articles. 
To specify an alternate history file, use the -+ flag. To specify an alternate input text history file, use the -h flag. expire uses 
the old dbz(3z) database to determine the size of the new one To ignore the old database, use the -: flag. 





expire usually just unlinks each file if it should be expired. If the -1 flag is used, then all articles after the first one are treated 
as if they could be symbolic links to the first one. In this case, the first article will not be renoved as long as any other cross- 
posts of the article remain. 


expire usually sends a pause command to the local inna(8) daemon when it needs exclusive access to the history file using 
the string Expiring as the reason. To give a different reason, use the -r flag. The process !D will be appended to the reason. 
When expire is finished and the new history fileis ready, it sends a go command. If inna isnot running, use the -n flag and 
expire will not send the pause or go commands. (For more details on the commands, see ct1inna(8).) N ote that expire 
only needs exclusive access for a very short time— long enough to see if any new articles arrived since it first hit the end of the 
fileand to rename the new files to the working files. 


If the -s flag is used, then expire will print a summary when it exits, showing the approximate number of kilobytes used by 
all deleted articles. 

If the -+ flag is used, then expire will generate a list of the files that should be removed on its standard output, and the new 
history file will be left in history.n, history.n.dir, and history.n.pag. This flag is useful for debugging when used with 
the -n and -s flags. N ote that if the -+ flag is used, then the name specified with that flag will be used instead of history. 

If the -x flag is used, then expire will not create any new history files. T his is most useful when combined with the -n, -s, 
and -+ flags to see how different expiration policies would change the amount of disk space used. 








If the -z flag is used, then articles are not renoved, but their names are written to the specified file. See the description of 
expirerm in news. daily(8). 


expire makes its decisions on the time the article arrived, as found in the history file. T his means articles are often kept a 
little longer than with other expiration programs that base their decisions on the article's posting date To use thearticle’s 
posting date, use the -p flag. Use the -w flag to “warp” time so that expire thinks it isrunning at sometime othe then the 
current time. T he value should be a signed floating-point number of the number of days to use as the offset. 


expireover 


If the -d flag is used, then the new history file and database is created in the specified directory, dir. This is useful when the 
filesystem does not have sufficient space to hold both the old and new history files. When this flag is used, expire leaves the 
server paused and creates a zero-length file named after the new history file, with an extension of .done to indicate that it has 
successfully completed the expiration. T he calling script should install the new history file and unpause the server. The -r 
flag should be used with this flag. 


If a filename is specified, it istaken as the control file and parsed according to the rules in expire.ct1(5). A single dash (-) 
may be used to read the file from standard input. If no file is specified, thefile /news/1ib/expire.ct1is read. 

expire usually complains about articles that are posted to newsgroups not mentioned in theactive file. To suppress this 
action, use the -q flag. 


The -v flag is used to increase the verbosity of the program, generating messages to standard output. T he level should bea 
number, where higher numbers result in more output. Lev onewill print totals of the various actions done (not valid if a 
new history file is not written), level two will print report on each individual file and level five results in more than oneline 
of output for every line processed. If the -g flag is given, then a one line summary equivalent to the output of -v1 and 
preceded by the current time will be appended to the specified file. 


HISTORY 


Written by Rich $alz (rsalzeuunet .uu.net) for InterN &tN ews. 


SEE ALSO 


ctlinnd(8), dbz(3z), expire.ct1(5), history(5), inna(8), inndcomm(3) 


expireover 

expireover— Expire entries from the news overview database. 
SYNOPSIS 

expireover [ -a ][-D overviewdir ][-f file ][-n ] 

[-O overview. fmt ][-s ][-v ][-z ][file... ] 
DESCRIPTION 


expireover expires entries from the news overview database. It reads a list of pathnames (relative to the spool directory, / 
news /spool) from the specified files or standard input if none are specified. (A filename of - may be used to specify the 
standard input.) It then removes any mention of those articles from the appropriate overview database If the -z flag is used, 
then the input is assumed to be sorted such that all entries for a newsgroup appear together so that it can be purged at once. 
This flag can be useful when used with the sorted output of expire(8)’s -z flag. 


If the -s flag is used, then expireover will read the spool directory for all groups mentioned in the active(5) file and 
remove the overview entries for any articles that do not appear. To specify an alternate file use the -+ flag; aname of - is 
taken to mean the standard input. 

The -a flag reads the spool directory and adds any missing overview entries. It will create files if necessary. This can be used 
to initialize a database or to sync up a overview database that may be lacking articles due to acrash. overchan should be 
running, to ensure that any incoming articles get included. U sing this flag implies the -s flag; the -+ flag may be used to add 
only a subset of the newsgroups. 

To seea list of the entries that would be added or deleted, use the -v flag. To perform no real updates, use the -n flag. 

The -p flag can be used to specify where the databases are stored. The default directory is /news/spool. 


The -o flag may be used to specify an alternate location for the overview. fmt(5) file thisis usually only useful for debug- 
ging. 
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HISTORY 


Written by Rob Robattson (rob@violet.berkeley.edu) and Rich $alz (rsalz@uunet .uu.net) with hap from D ave 
Laurence (tale@uunet.uu.net) for InterN &N ews. 


SEE ALSO 


expire(8), overview. fmt(5) 


fastrm 

fastrm— Quickly ranovea set of files. 
SYNOPSIS 

fastrm [ -d ][-e ][-uN ][-sM ][-cl ] base directory 
DESCRIPTION 


fastrm readsa list of files, one per line from its standard input and removes them. If afileis not an absolute pathname it is 
taken rdative to the directory specified on the command line. The base directory parameter must be a simple absolute 
pathname— that is, it must not contain any /./ or /../ references. 


fastrm is designed to be faster than the typical ! xargs rm pipdine For example, fastrm will usually chdir(2) into a 
directory before renoving files from it. If the input is sorted, this means that most files to be renoved will be simple names. 


fastrm assumes that its input is valid and that it is safe to just do an unlink(2) call for each item to be removed. As a safety 
measure, if fastrm is run by root, it will first stat(2) the item to make sure that it is not a directory before unlinking it. 


If the -d flag is used, then no files are renoved. Instead, a list of the files to be removed, in debug form, is printed on the 
standard output. Each line contains either the current directory of fastrm at the time it would do the unlink and then the 
pathname it would pass to unlink(2) as two fields separated by white space and a / or the absolute pathname (a single field) 
of files it would unlink using the absolute pathname. 





If the -e flag is used, fastrm will treat an enpty input file (stain) asan error. Thisis most useful when fastrm iSlast ina 
pipdine after a preceding sort(1) because if the sort fails, there will usually be no output to become input of fastrm. 


If the -u flag is used, then fastrm makes further assumptions about its work environment— in particular, that there are no 
symbolic links in the target tree. T his flag also suggests that it is probably faster to referencethe path ../../../ rather than 
start from the root and come down (note that this probably isn’t true on systems that have a namei cache, which usually 
holds everything except . .). The optional n is an integer that specifies the maximum number of .. segments to use— paths 
that would use more than this use the absolute pathname (from the root) instead. If the -u flag is given without a value -u1 
is assumed. 





If the -s flag is used, then fastrm will perform the unlinks from one directory— that is, when a group of filesin one 
directory appear in the input consecutively— in the order that the files appear in the directory from which they are to be 
removed. The intent of this flag isthat on systems that have a per-process directory cache, finding files in the directory 
should be faster. It can have smaller benefits on other systems. T he optional m is an integer that specifies the number of files 
that must be going to be renoved from one directory before the files will be ordered. If the -s flag is given without a value 
-s5 isassumed. When the directory reordering isin use, fastrm will avoid attempting to unlink files that it can’t seein the 
directory, which can speed it appreciably when many of the filenames have already been removed. 


The -c flag may be given to instruct fastrm when it should chdir(2). If the number of files to be unlinked from a directory 
iS at least 1, then fastrm will chdir and unlink thefiles from in thedirectory. O therwise, it will build a path relative to its 
current directory. If -c is given without the optional integer 1, then -c1 is assumed, which will cause fastrm to always use 
chdir. If -c isnot used at all, then -c3 is assumed. Use -co to prevent fastrm from ever using chdir(2). 


fdformat 


T herve are also -a and -r options, which do nothing at all except allow you to say fastrm -usa, fastrm -ussr, Of fastrm 
-user. T hese happen to often be convenient sets of options to use. 


fastrm exits with a status of 0 if there were no problemsor 1 if something went wrong. Attempting to renovea file that does 
not exist is not considered a problem. If the program exits with a nonzero status, it is probably a good idea to feed the list of 
filesinto an xargs rmpipeline 


fdformat 


fdformat— Low-level formats a floppy disk. 


SYNOPSIS 


fdformat [ -n ] device 


DESCRIPTION 
fdformat does a low-level format on a floppy disk. device is usually one of the following (for floppy devices, the major is 2, 
and the minor is shown for informational purposes only): 

/dev/fded360 (minor =4) 

/dev/fd0h1200 (minor =8) 

/dev/fdeD360 (minor =12 
/dev/fd0H360 (minor =12 
/dev/fd0D720 (minor =16 
/dev/fd0H720 (minor =16 
/dev/fdoh36e (minor =20 
/dev/fd0h720 (minor =24 
/dev/fd0H1440 (minor =28) 
/dev/fd1d360 (minor =5) 

@ 
( 
( 
( 
( 
( 





) 
) 
) 
) 
) 
) 


/dev/fd1h1200 (minor =9) 
/dev/fd1D360 (minor =13) 
/dev/fd1H360 (minor =13) 
/dev/#d1D720 (minor =17) 
/dev/#d1H720 (minor =17) 
/dev/fd1h360 (minor =21) 
/dev/fd1h720 (minor =25) 
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/dev/#d1H1440 (minor =29) 








The genaic floppy devices, /dev/fde and /dev/fd1, will fail to work with fdformat when a non-standard format is being 
used or if the format has not been autodetected earlier. In this case, use setfdprm(8) to load the disk parameters. 


OPTIONS 


n No verify. This option will disable the verification that is performed after the format. 


SEE ALSO 


fd(4), setfdprm(8), mkfs(8), emkfs(8) 
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AUTHOR 


Werner Almesberger (almesber@nessie.cs.id.ethz.ch) 
Linux 0.99, 1 February 1993 


fdisk 


fdisk— Partition table manipulator for Linux. 


SYNOPSIS 


fdisk [ -1 ] [ -v ] [ -s partition] [ device ] 


DESCRIPTION 
fdisk isamenu-driven program for manipulation of the hard disk partition table T hedeviceis usually one of the following: 
/dev/hda 
/dev/hdb 


/dev/sda 
/dev/sdb 


The partition is a device name followed by a partition number. For example /dev/hdat is the first partition on the first hard 
disk in the system. 


If possible, fdisk will obtain the disk geometry automatically. T his is not necessarily the physical disk geometry but is the 
disk geometry that M S-D OS uses for the partition table. If fdisk warns you that you need to set the disk geometry, please 
bdieve this statement and set the geometry. This should only be necessary with certain SCSI host adapters (the drivers for 
which are rapidly being modified to provide geometry information automatically). 


Whenever a partition table is printed, a consistency check is performed on the partition table entries. T his check verifies that 
the physical and logical start and end points are identical and that the partition starts and ends on acylinder boundary 
(except for the first partition). 


Old versions of fdisk (all versions prior to 1.1r including 0.93) incorrectly mapped the cylinder /head/sector specification 
onto absolute sectors. This might result in the first partition on a drive failing the consistency check. If you use LILO to 
boot, this situation can be ignored. H owever, there are reports that the O S/2 boot manager will not boot a partition with 
inconsistent data. 


Some versions of MS-DOS create a first partition that does not begin on acylinder boundary but on sector 2 of the first 
cylinder. Partitions beginning in cylinder 1 cannot begin on acylinder boundary, but this is unlikely to cause difficulty 
unless you have O S/2 on your machine. 


In version 1.1r, aBLKRRPART ioct1() is peformed before exiting when the partition table is updated. Thisis primarily to 
ensure that removable SC SI disks have their partition table information updated. If the kernel does not update its partition 
table information, fdisk warns you to reboot. If you do not reboot your system after recd ving such a warning, you might 
lose or corrupt the data on the disk. Sometimes BLkRAPART fails silently; when installing Linux, you should always reboot 
after editing the partition table 


DOS 6.X WARNING 


TheD OS 6.x Format command looks for some information in the first sector of the data area of the partition and treats this 
information as more reliable than the information in the partition table. bos FormaT expects D OS Forsk to clear the first 
512 bytes of the data area of a partition whenever a size change occurs. Dos ForMAT will look at this extra information even if 
the /u flag is given 





filechan 1297 


The bottom line is that if you us¢ cfdisk Or fdisk to change the sizeof aDOS partition table entry, then you must also use 
dd to zero the first 512 bytes of that partition before using pos _ForMAT to format the partition. For example if you were 
using cfdisk to makea DOS partition table entry for /dev/hdat, then (after exiting fdisk or cfdisk and rebooting Linux 
so that the partition table information is valid) you would usethe command dd if=/dev/zero of=/dev/hda1 bs=512 
count=1 to zero the first 512 bytes of the partition. 


W econsider this abug in bos FORMAT and Dos FDISK. 


Be extremely careful if you use the ad command because a small typo can make all of the data on your disk usdess. 


For best results, you should always use an O S-specific partition table program. For example, you should makeDOS 
partitions with the bos FDISK program and Linux partitions with the Linux fdisk or Linux cfdisk program. 


OPTIONS 

“Vv Prints version number of fdisk program. 

<i Lists the partition tables for /dev/hda, /dev/hdb, /dev/sda, /dev/sdb, /dev/sde, / 
dev/sdd, /dev/sde, /dev/sdf, /dev/sdg, and /dev/sdh and then exits. 

-s partition If the partition isnotaDOS partition (the partition ID is greater than 10), then the 
size of that partition is printed on the standard output. T his value is usually used as 
an argument to themkfs(8) program to specify the size of the partition that will be 
formatted. 

BUGS 


Although this man page (written by faith@cs.unc. edu) is poor, there is excdlent documentation in the README. fdisk file 
(written by LeBlanc@mec.ac.uk) that should always be with the fdisk distribution. If you cannot find this filein the uti1- 
linux -* directory or with the fdisk.c source file then you should write to the distributor of your version of fdisk and 
complain that you do not have all of the available documentation. 


AUTHOR 


AN. LeBlanc (LeBlanc@mce .ac.uk). V1.0r: SCSI and extfs support added by Rik Faith (faithe@cs.unc. edu). v1.1r: Bug 
fixes and enhancements by Rik Faith (faith@cs.unc. edu), with special thanksto M ichad Bischoff (i1041905@ws.rz.tu- 
bs.de OF mbi@mo.math.nat.tu-bs.de). V1.3: Latest nhancenants and bug fixes by A.V. LeBlanc, including the addition 
of the -s option. v2.0: Disks larger than 2GB are now fully supported, thanksto Remy Card’s 11seek support. 


Linux 1.0, 3 June1995 


filechan 


filechan— File-writing back end for InterN e&tN ews. 


SYNOPSIS 


filechan [ -d directory ][-f fields ][-m mapfile ][-p pidfile ] 


DESCRIPTION 


filechan reads lines from standard input and copies certain fidds in each line into files named by other fields within the 
line filechan isintended to be called by inna(8) as a channel feed. (It is not a full exploder and does not accept commands; 
see newsfeeds(5) for a description of the difference and buffchan(8) for an exploder program.) 


filechan input is interpreted as a set of lines. Each line contains a fixed number of initial fidds, followed by a variable 
number of filename fields. All fidds in a line are separated by whitespace The default number of initial fiddsis one the -F 
flag may be used to specify a different number of fields. 
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For each line of input, #ilechan writes the initial fields, separated by whitespace and followed by a newline, to each of the 
files named in the filename fields. W hen writing to afile, filechan opens it in append mode and tries to lock it and change 
the ownership to the user and group who owns the directory where the file is bang written. 


By default, filechan writes its argumentsinto the directory /news/spool/out. going. T he -d flag may be used to specify a 
directory the program should change to before starting. 


If the -p flag is used, the program will write a line containing its process|D (in text) to the specified file. 
If filechan isinvoked with -f 2 and given the following input: 


news/software/b/132 <1643@munnari.oz.au>foo uunet 
news/software/b/133 <102060@litchi.foo.com> uunet munnari 
comp/sources/unix/2002 <999@news.foo.com>foo uunet munnari 


Then the file foo will have these lines: 


news/software/b/132 <1643@munnari.oz.au> 
comp/sources/unix/2002 <999@news. foo. com> 


The file munnari will have these lines: 


news/software/b/133 <102060@litchi.f00.com> 
comp/sources/unix/2002 <999@news. foo. com> 


The file uunet will have these lines: 


news/software/b/132 <1643@munnari.oz.au> 
news/software/b/133 <102060@litchi.foo.com> 
comp/sources/unix/2002 <999@news. foo. com> 


Because the time window in which afileis open is very small, complicated flushing and locking protocols are not needed; a 
mv(1) followed by a si1eep(1) for a couple of seconds is sufficient. 


A map file may be specified by using the -m flag. Blank lines and lines starting with anumber sign (#) are ignored. All other 
lines should have two hostnames separated by a colon. The first fidd is the name that may appear in the input stream; the 
second field names the file to be used when the name in the first field appears. For example, the following map file may be 
used to map the short namesto the full domain names: 


# This is a comment uunet:news.uu.net foo:foo.com munnari:munnari.oz.au 


HISTORY 


Written by Robet Elz (kre@munnari.oz.au); flags added by Rich $alz (rsalzeuunet.uu.net). 


SEE ALSO 


buffchan(8), innd(8), newsfeeds(5) 


fsck 


fsck— Check and repair a Linux filesystem. 


SYNOPSIS 


fsck [ -AVRTN ][-S ][-t fstype ][fs-options ] filesys [ ... ] 


DESCRIPTION 


fsck is used to check and optionally repair a Linux filesystem. filesys is ather the device name (such as /dev/hda1 OF /dev/ 
sdb2) or the mount point (such as /, /usr, Or /home) for the filesystem. If this fsck has several filesystems on different 
physical disk drives to check, this fsck will try to run then in parallel. T his reduces the total amount time it takes to check 
all of the filesystems because fsck takes advantage of the parallelism of multiple disk spindles. 


The exit code returned by fsck isthe sum of the following conditions: 


0 No errors 

1 Filesystem errors corrected 

2 System should be rebooted 

4 Filesystem errors left uncorrected 
8 Operational error 

16 Usage or syntax error 

128 Shared library error 


The exit code returned when all filesystems are checked using the -a option is the bitwise or of the exit codes for each file 
system that is checked. 


In actuality, fsck is simply a front end for the various filesystem checkers (fsck. fstype) available under Linux. T he 
filesystem-specific checker is searched for in /sbin first, then in /etc/fs and /etc, and finally in the directories listed in the 
PATH environment variable. Please see the filesystem-specific checker manual pages for further details. 


OPTIONS 

“A Walk through the /etc/fstab file and try to check all filesystems in onerun. This 
option is typically used from the /etc/re system initialization file, instead of 
multiple commands for checking a single file system. 

-R W hen checking all filesystems with the -a flag, skip the root file system (in case it’s 
already mounted read-write). 

-T Don’t show thetitle on startup. 

-N Don’t execute; just show what would be done 

“8 Sevialize fsck operations. This isa good idea if you checking multiple filesystems in 
and the checkers are in an interactive mode (N ote: e2fsck runsin an interactive 
mode by default. To make e2fsck run in anon-interactive mode, you must either 
specify the -p or -a option, if you want errorsto be corrected automatically, or the - 
n option if you do not.) 

-V Produce verbose output, including all filesystem-specific commands that are 
executed. 

-tfstype Specifies the type of filesystem to be checked. When the -a flag is specified, only 


filesystems that match fstype are checked. If fstype is prefixed with no, only 
filesystems whose filesystem do not match fstype are checked. 
Usually, the filesystem type is deduced by searching forfilesys in the /etc/fstab 
fileand using the corresponding entry. If the type can not be deduced, fsck will use 
the type specified by the -t option if it specifies a unique filesystem type. If this type 
isnot available the the default filesystem type (currently ext2) is used. 

fs-options Any options that are not understood by fsck, or that follow the - option are treated 
as filesystem-specific options to be passed to the filesystem-specific checker. 
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Currently, standardized filesystem-specific options are somewhat in flux. Although not guaranteed, the following options are 
supported by most filesystem checkers: 


-a Automatically repair the filesystem without any questions. (U se this option with caution.) N ote 
that e2fsck supports -a for backwards compatibility only. This option is mapped to e2tsck’s -p 
option, which is safe to use, unlike the -a option that most filesystem checkers support. 


-r Interactively repair the filesystem (ask for confirmations). N ote: It is generally a bad idea to use 
this option if multiple fsck’s are run in paralld. Also note that this is e2fsck default behavior; it 
supports this option for backwards compatibility reasons only. 


AUTHOR 


TheodoreT s'o (tytso@mit.edu) 


The manual page was shamelessly adapted from D avid Engel and Fred van Kempen’s ganeric fsck front-end program, which 
in turn was shameessly adapted from Remy Card's version for the ext2 filesystem. 


FILES 


/etc/fstab 
SEE ALSO 
fstab(5), mkfs(8), fsck.minix(8), fsck.ext2(8) or e2fsck(8), fsck.xiats(8) 
Vergon 0.5b, N ovenber 1994 


fsck .minix 

fsck.minix—A filesystem consistency checker for Linux. 
SYNOPSIS 

fsck.minix [ -larvsmf ] device 
DESCRIPTION 


fsck.minix performs a consistency check for the Linux M IN IX filesystem. T he current version supports the 14 character and 
30 character filename options. 


The program assumes the filesystem is quiescent. fsck.minix should not be used on a mounted device unless you can be sure 
nobody is writing to it (and renanber that the kernel can write to it when it searches for files). 

The device will usually have the following form: 

/dev/hda[ 1-8] 

/dev/hdb[ 1-8] 


/dev/sda[1-8] 
/dev/sdb[1-8] 


If the filesystem was changed (that is, repaired), then fsck.minix will print File system has changed and will sync(2) three 
times before exiting. Because Linux does not currently have raw devices, there is no need to reboot at this time (versus a 
system that does have raw devices). 


WARNING 


fsck.minix should not be used on a mounted filesystem. U sing fsck.minix on amounted filesystem is very dangerous due to 
the possibility that deleted files are still in use and can seriously damage a perfectly good filesystem! If you absolutely have to 
run fsck.minix on amounted filesystem (that is, the root filesysten), make sure nothing is writing to the disk and that no 
files are “zombies” waiting for ddetion. 


OPTIONS 
“1 Lists all filenames. 
-r Performs interactive repairs. 
-a Performs automatic repairs (this option implies -r) and serves to answer all of the questions asked with the 


default. N ote that this can be extremely dangerousin the case of extensive filesystem damage. 
“V Verbose. 


-s Outputs super-block information. 
-m Activates M IN 1X-like “mode not cleared” warnings. 
-f Forcefilesystem check even if the filesystem was marked as valid. (T his marking is done by the kernd 
when thefilesystem is unmounted.) 
SEE ALSO 
fsck(8), fsck.ext(8), fsck.ext2(8), fsck.xiafs(8), mkfs(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8), reboot(8) 
DIAGNOSTICS 


There are numerous diagnostic messages. The ones mentioned here are the most commonly se in normal usage. 
If the device does not exist, fsck.minix will print unable to read super block. If the device exists but isnot aMINIX 
filesystem, fsck.minix will print Bad magic number in super -block. 


EXIT CODES 


The exit code returned by fsck.minix isthe sum of the following: 


t) No errors. 

3 Filesystem errors corrected; systen should be rebooted if filesystaen was mounted. 
4 Filesystem errors left uncorrected. 

8 O perational error. 

16 U sage or syntax error. 


In point of fact, only a, 3, 4, 7, 8, and 16 can ever be returned. 


AUTHOR 


Linus Torvalds (torvalds@cs.helsinki.fi). Error code values by Rik Faith (faithecs.unc. edu). Added support for filesystem 
valid flag: Dr. W ettstein (gregswind. uucp@plains.nodak.edu). Check to prevent fsck of mounted filesysten added by Daniel 
Quinlan (quinilan@yggdrasil.com). 


Linux 0.99, 10 January 1994 


ftpd— DARPA Internet File Transfer Protocol server. 


SYNOPSIS 


ftpd [-d] [-1] [-t timeout] [-T maxtimeout ] 


DESCRIPTION 


ftpd isthe DARPA Internet File T ransfer Protocol server process. The server uses the TCP protocol and listens at the port 
specified in the FTP service specification; see services(5). 
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Available options: 


aft FEF a 


D ebugging information is written to the syslog. 
Each FTP 1 session islogged in the syslog. 
The inactivity timeout period is set to timeout seconds. (T he default is15 minutes.) 


A client can also request a different timeout period; the maximum period allowed can be set to timeout 
seconds with the -t option. T he default limit is2 hours. 


TheFTP server currently supports the following FT P requests; case is not distinguished. 





Request D excription 

ABOR Abort previous command 

ACCT Specify account (ignored) 

ALLO Allocate storage (vacuously) 

APPE Append to afile 

cDUP Change to parent of current working directory 
cwD Change working directory 

DELE D elete a file 

HELP Give hdp information 

LIST Give list filesin a directory ('' 1s -1gA '') 
MKD M ake adirectory 

MDTM Show last modification time of file 

MODE Specify data transfer mode 

NLST Give name list of filesin directory 

NOOP Do nothing 

PASS Specify password 

PASV Prepare for server-to-server transfer 

PORT Specify data connection port 

PWD Print the current working directory 

QUIT T erminate session 

REST Restart incomplete transfer 

RETR Retrievea file 

RMD Removea directory 

RNFR Specify reiame-from filename 

RNTO Specify rerame-to filename 

SITE N onstandard commands (see next section) 
SIZE Return size of file 

STAT Return status of server 

STOR Storea file 

STOU Store a file with aunique name 

STRU Specify data transfer structure 

SYST show operating system type of server systan 
TYPE specify data transfer type 

USER specify username 

XCUP change to parent of current working directory (deprecated) 





Request D excription 

XcWD change working directory (deprecated) 

XMIKD make a directory (deprecated) 

XPWD print the current working directory (deprecated) 
XRMD remove a directory (deprecated) 


The following non-standard or UN |1X-specific commands are supported by thes1Te request: 





Request D esrription Example 

UMASK Change umask SITE UMASK 002 
IDLE Se idle timer SITE IDLE 60 
CHMOD Change mode of afile SITE CHMOD 755 
HELP Give hdp information SITE HELP 


Theremaining FT P requests specified in Internet RFC 959 are recognized but not implanented. motm and size are not 
specified in RFC 959 but will appear in thenext updated FTP RFC. 

TheFTP server will abort an active file transfer only when the aBor command is preceded by aT elnet “Interrupt Process” 
(IP) signal and aT elnet “Synch” signal in the command T dnet stream, as described in Internet RFC 959. If astat 
command is recaved during a data transfer, preceded by aT dnet IP and synch, transfer status will be returned. 

ftpd interprets filenames according to the globbing conventions used by csh(1). T his allows users to utilize the 
metacharacters Li & *7[]. 


ftpd authenticates users according to four rules: 
The username must be in the password database and not havea null password. In this case, a password must be provided 
by the client before any file operations may be peformed. 
The username must not appear in the file (see ftpusers(5)). 
Theuser must havea standard shdl returned by getusershe11(3). 


If the username is anonymous or FT P, an anonymous FT P account must be present in the password file (user FTP). In 
this case, the user is allowed to log in by specifying any password. (By convention, thisis given asthe client host’s name) 


In the last case, ftpa takes special measures to restrict the client’s access privileges. The server performs a chroot(2) command 
to the home directory of the FT P user. So that system security is not breached, it is recommended that the FT P subtree be 
constructed with care; the following rules are recommended: 


“ftp M ake the home directory owned by root and unwritable by anyone 

~ftp/bin M ake this directory owned by root and unwritable by anyone The program 1s(1) must be present to 
support the 1ist command. This program should have mode 111. 

~ftp/etc M ake this directory owned by root and unwritable by anyone The files passwa(5) and group(5) must be 


present for the 1s command to be ableto produce owner names rather than numbers. T he password field 
in passwd isnot used and should not contain real encrypted passwords. T hese files should be mode 444 and 
owned by root. D on’t use the systen’s /etc/passwd file as the password file or the system’s /etc/group file 
as the group filein the ~ftp/etc directory. 


Pa ~ftp/pub M ake this directory mode 755 and owned by root. Create a subdirectory in ~ftp/pub with the appropriate 
mode (777 or 733) if you want to allow normal users to upload files. 


SEE ALSO 


ftp(1), getusershe11(3), ftpusers(5), sysloga(8) 


BUGS 


The anonymous account is inherently dangerous and should avoided when possible. 
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The server must run as the super-user to create sockets with privileged port numbers. It maintains an effective use 1D of the 
logged-in user, reverting to the super-user only when binding addresses to sockets. T he possible security holes have been 
extensively scrutinized but are possibly incomplete 


HISTORY 
The command appeared in BSD 4.2. 
BSD 4.2, 16 March 1991 


ifconfig 
ifconfig— Configure a network interface. 


SYNOPSIS 


ifconfig [interface] 
ifconfig interface [aftype] options | address ... 


DESCRIPTION 


ifconfig iS used to set up (and maintain thereafter) the kernel-resident network interfaces. It is used at boot time to configure 
most of them to arunning state. After that, it is usually only needed when debugging or when system tuning is needed. 








If no arguments are given, ifconfig just displays the status of the currently defined interfaces. If the single interface argument 
is given, it displays the status of the given interface only. Otherwise it assumes that things have to be set up. 


ADDRESS FAMILIES 


If the first argument after the interface name is recognized as the name of a supported address family, that address family is 
used for decoding and displaying all protocol addresses. C urrently supported address families include inet (TCP/IP, default) 
and ax25 (AM PR Packet Radio.) 


OPTIONS 

interface The name of theN ET interface. This usually isa name such aSwde, s13, or something like that: 
a device driver name followed by a unit number. 

up This flag causes the interface to be activated. It isimplicitly specified if theinterface is given a 
new address (see below). 

down This flag causes the driver for this interface to be shut down and is useful when things start 
going wrong. 

[-]arp Enable or disable the use of the ARP protocol on this interface. If the minus (-) sign is present, 
the flag is turned OFF. 

[-]trailers Enable or disable the use of trailers on Ethernet frames. T his isnot used in the current 
implementation of NET. 

[-]allmulti Enable or disable the promiscuous mode of the interface. T his means that all incoming frames 
get sent to the network layer of the systen kernel, allowing for networking monitoring. 

metric N This parameter sets the interface metric. It is not used at present, but we implement it for the 
future 

mtu N This parameter sets the M aximum Transfer Unit (MTU) of an interface For Ethernet, thisisa 


number in the range of 1000-2000 (default is 1500). For SLIP, use something between 200 and 
4096. N ote that the current implenentation does not handle|P fragmentation yet, so you'd 
better make the MTU large enough! 

dstaddr addr Se the “other end’s” IP address in case of a point-to-point link, such as PPP. T his keyword is 
obsoleted by thenew pointopoint keyword. 


inetd 


netmask addr Se the |P network mask for this interface. T his value defaults to the usual classA, B, or C 
network mask (as deducted from the interface IP address), but it can be set to any value for the 
use of subnetting. 

[-]broadcast [addr] If the address argument is also given, set the protocol broadcast address for this interface 
Otherwise, it only sets the 1FF_BroapcasT flag of the interface. If the keyword was preceded by a 
minus (-) sign, then the flag is cleared instead. 

[-]pointopoint [addr] This keyword enables the point-to-point mode of an interface, meaning that it is a direct link 
between two machines with nobody else listening on it. (At least we hope that this is the case, 
grin :-).) 

If the address argument is also given, set the protocol address of the other side of the link, just 
like the obsolete dstaddr keyword does. O therwise, it only sets the IFF_POINTOPOINT flag of the 
interface. If the keyword was preceded by a minus (-) sign, then the flag is cleared instead. 


hw Se the hardware address of this interface if the device driver supports this operation. T he 
keyword must be followed by the name of the hardware class and the printable ASCII 
equivalent of the hardware address. H ardware classes currently supported include ether 
(Ethernet), ax25 (AM PR AX.25), and ppp, although the latter is not really supported yet. 


address The hostname or IP address (a hostname will be resolved into an IP address) of that interface. 
This parameter is required, although the syntax doesn’t currently require it. 


FILES 


/dev/net/socket 


BUGS 
N one so far, although the syntax checking could be better. 


AUTHOR 
Fred N. van Kempen (waltje@uwalt.nl.mugnet.org) 
6 Octobe 1993 


inetd 


inetd— Interne superserver. 


SYNOPSIS 


inetd [-d] [configuration file] 


DESCRIPTION 


inetd should be run at boot time by /etc/rc. local (See rc(8)). It then listens for connections on cettain Internet sockets. 
When a connection is found on one of its sockets, it decides what service the socket corresponds to and invokes a program to 
service the request. After the program is finished, it continues to listen on the socket (except in some cases, which are 
described later). Essentially, inetd allows running one daemon to invoke several others, reducing load on the system. 


The option available for ineta: 
-d Turns on debugging. 


Upon execution, inetd reads its configuration information from a configuration file which, by default, is /etc/inetd.conf. 
There must bean entry for each fidd of the configuration file, with entries for each field separated by atab or a space. 
Comments are denoted by a # at the beginning of aline T here must be an entry for each field. T he fields of the configura- 
tion file are as follows: 
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service name 
socket type 
protocol 

wait /nowait[.max] 
user[.group] 
server program 


server program arguments 


To specify an Sun-RPC based service, the entry would contain these fields: 
service name/version 
socket type 
rpc/protocol 
wait /nowait[.max] 
user[.group] 
server program 


server program arguments 


Theservice name entry is the name of a valid servicein the file /etc/services . For internal services, the sevice name must 
be the officia name of the service (that is, the first entry in /etc/services). When used to specify aSun-RPC based service, 
this field isa valid RPC servicenamein the file /etc/rpc. The part on the right of the; isthe RPC version number. This can 
simply be asingle numevic argument or a range of versions. A range is bounded by the low version to the high version 

- rusers/1-3. 


The socket type should be one of stream, dgram, raw, rdm, OF seqpacket, deoending on whether the socket is a stream, 
datagram, raw, reliably ddivered message, or sequenced packet socket. 


The protocol must be a valid protocol as given in /etc/protocols. Examples might be tcp or udp. Rpc-based services are 
specified with the rpc/tcp or rpc/udp servicetype. 


The wait/nowait entry is applicable to datagram sockets only. (O ther sockets should have a nowait entry in this space) If a 
datagram server connects to its peer, freeing the socket so inetd can receive further messages on the socket, it is said to bea 
multithreaded server and should use the nowait entry. For datagram servers that process all incoming datagrams on a socket 
and eventually time out, the server is said to be single threaded and should usea wait entry. comsat(8), biff(1), and talka(8) 
are examples of the latter type of datagram server. Tftpd(8) is an exception; it is a datagram server that establishes pseudo- 
connections. 


It must be listed as wait in order to avoid a race the server reads the first packet, creates a new socket, and then forks and 
exits to allow ineta to check for new service requests to spawn new servers. The optional max suffix (separated from wait or 
nowait by a dot) specifies the maximum number of server instances that may be spawned from inetd within an interval of 60 
seconds. When omitted, max defaults to 40. 


The user entry should contain the username of the user as whom the server should run. This allows for servers to be given 
less permission than root. An optional group name can be specified by appending a dot to the usaname followed by the 
group name. This allows for servers to run with a different (primary) group ID than specified in the password file If a group 
is specified and the user is not root, the supplementary groups associated with that user will still be set. 


The servve-program entry should contain the pathname of the program that is to be executed by inetd when a request is 
found on its socket. If inetd provides this service internally, this entry should be internal. 


Theserver program arguments should appear just as arguments normally do, starting with argv[o], which isthe name of the 
program. If the service is provided internally, the word interna should take the place of this entry. 


inetd provides several trivial services internally by use of routines within itsaf. T hese services are echo, discard, chargen 
(character generator), daytime (human readable time), and time (machine readable time in the form of thenumber of seconds 
since midnight, January 1, 1900). All of these services are T CP based. For details of these services, consult the appropriate 
RFC from the N ework Information C enter. 


init, telinit 


inetd rereads its configuration file when it receives a hangup signal, steHup. Services may be added, deleted, or modified 
when the configuration file is reread. inetd creates a file /etc/inetd.pid that contains its process identifier. 


SEE ALSO 


comsat(8), fingerd(8), ftpa(8), rexecd(8), rlogina(8), rshd(8), telneta(8), tftpd(8) 


HISTORY 
The command appeared in BSD 4.3. Support for Sun-RPC based services is modeled after that provided by Sun-OS 4.1. 


BSD 4.3, 16 March 1991 


init, telinit 
init, telinit— Process control initialization. 


SYNOPSIS 


/sbin/init [ -t sec ][0123456SsQq ] 
/sbin/telinit [ -t sec ][0123456sSQqabc ] 


DESCRIPTION 
init 
init isthe father of all processes. Its primary role is to create processes from a script stored in the file /etc/inittab (see 


inittab(5)). T his file usually has entries that cause init to Spawn gettys on each line that users can log in. It also controls 
autonomous processes required by any particular system. 


A run level is a software configuration of the system that allows only a sdected group of processes to exist. The processes 
spawned by init for each of these run leve's are defined in the /etc/inittab file init can bein oneof aght run levels, a6 and 
s ors. Therun level is changed by having a privileged user run /sbin/telinit, which sends appropriate signals to init, telling 
it which run level to change to. 


After init is invoked as the last step of the kernel booting, it looks for the file /etc/inittab to seeif thereisan etry of the 
type initdefault (See inittab(5)). initdefault determines the initial run levd of the system. If thereis no such entry or no 
/etc/inittab at all, arun levd must be entered at the systen console. 





Run level s or s brings the systen to single-user mode and does not require an /etc/initttab file. In single user mode 
/bin/sh iSinvoked on /dev/console. 


/dev/console need not necessarily be the physical system console. When init istold to enter sngle user mode or run level 1 
(either directly, by init s, or by telling shutdown to enter maintenance mode), it will link the terminal line the command 
was executed from to /dev/console. T he device /dev/systty iS called the physical system console and the device /dev/console 
is called the logical system console If the logical system console is not the physical system console, pressing the combination 
Ctrl+Alt+D d on the physical systen console will force a relink of /dev/console to /dev/systty. A tarminal line can only 
become the logical console if it’s listed in the file /etc/securetty. All thisisin preparation of the day that the Linux kernal 
will support serial consoles. 


Beware: If you want to run x or anything else that is aware of Virtual C onsoles, the logical system console (/dev/console) 
needs to be the same as the physical system console (/dev/systty). 


When entering single-user mode, init reads the console’s ioct1(2) states from /etc/ioct1.save. If this file does not exist, init 
initializes the line at 9600 baud and with cLocat settings. When init leaves single-user mode, it stores the console’s ioct1 
settings in this file so it can reuse them for the next single-user session. If the logical system console is changed to another 
terminal line, the settings of the line from which the init or telinit Command was given are stored in /etc/ioct1.save too, 
so that the terminal line will be initialized correctly in single user mode. 
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When entering a multi-user mode the first time, init performs the boot and bootwait entries to allow filesystems to be 
mounted before users can log in. Then all entries matching the run level are processed. 


Each time a child terminates, init records the fact and the reason it died in /etc/utmp and /var/adm/wtmp if these files exist. 


After it has spawned all the processes specified, init waits for one of its descendant processes to die a powerfail signal, or a 
signal by /sbin/telinit to changethe system’s run levd. When one of these three conditions occurs, it re examines the 
/etc/inittab file N ew entries can be added to thisfile at any time H owever, init still waits for one of the three conditions 
to occur. T 0 provide for an instantaneous response, the a or q command can wake up init to reexamine the /etc/inittab 
file. 


If init isnot in single user mode and receives a powerfail signal, special powerfail entries are invoked. 


W hen init is requested to change the run level, it sends the warning signal stcTerm to all processes that are undefined in the 
new run levd. It then waits 20 seconds before forcibly terminating these processes via the kill signal STGKILL. 


N ote that init assumes that all these processes (and their descendants) remain in the same process group that init originally 
created for them. If any process changes its process group affiliation, it will not receive these signals. Such processes need to 
be terminated separately. 


telinit 


/sbin/telinit islinked to /sbin/init. It takesa one-characte argument and signals init to perform the appropriate action. 
The following arguments serve as directives to /sbin/telinit: 


0, 1, 2,3, 4, 5, Ore Tall /sbin/init to switch to the specified run levd. 

a,b, c Tall /sbin/init to process only those /etc/inittab file entries having run level a, b, orc. 
aorg Tell /sbin/init to reexamine the /etc/inittab file. 

sors Tall /sbin/init to switch to single user mode 


/sbin/telinit Can also tell init how much time it should wait between sending processes the Term and thekILL signal; the 
default is 20 seconds, but it can be changed by the -t sec option. 


/sbin/telinit can be invoked only by users with appropriate privileges. 


RUN LEVELS 


Run levels 0, 1, and 6 are reserved. Run level 0 is used to halt the system, run levd 6 is used to reboot the system, and run 
level 1 is used to get the system down into single-user mode. Run level s isnot really meant to be used directly but should be 
used by scripts that are executed when entering run levd 1. For more information on this, see the man pages for shutdown(1) 
and inittab(5). 


FILES 


/etc/inittab 
/dev/console 
/dev/systty 
/etc/ioctl.save 
/etc/utmp 
/var/adm/wtmp 


CONFORMING TO 


init is compatible with the Systen V init. Thescripts that are used with it, however, are mostly modeled after the BSD 
startup scripts. T here are startup scripts available that let Linux boot more like a Systen V system, but most people find 
them too complex. 


WARNINGS 


init assumes that processes and descendants of processes remain in the same process group that was originally created for 
them. If the processes change their group, init can’t kill then and you might end up with two processes reading from one 
terminal line 


innd, inndstart 
DIAGNOSTICS 


If /sbin/init finds that it is continuously respawning an entry more than ten timesin two minutes, it will assume that there 
isan error in the command string, generate an error message on the system console, and refuse to respawn this entry until 
either five minutes has elapsed or it recaves asignal. This prevents it from eating up system resources when someone makes a 
typographical error in the /etc/inittab file or the program for the entry is renoved. 
AUTHOR 
Miquel van Smoorenburg (miquels@drinkel.n1.mugnet.org); initial manual page by M ichad H aardt 
(u31b3hs@pool. informatik. rwth-aachen.de). 
SEE ALSO 
getty(1), 1ogin(1), sh(1), who(1), shutdown(1), kil1(2), inittab(5), utmp(5) 
19 January 1994 


innd, inndstart 


innd, inndstart— InterN etN ews daemon. 


SYNOPSIS 
innd [ -a ][-c days ][-d ][-f ][-i count ][-o count ][-1 size ] 
[-m mode ][-n flag ] [ -p port ][-r ][-s ][-S host ][-t timeout ][-u ][-x ] 
inndstart [ flags ] 

DESCRIPTION 


innd, the InterN etN ews daemon, handles all incoming NNTP feeds. It reads the active(5), newsfeeds(5), and hosts.nntp(5) 
files into memory. It then opens the N NTP port to recave articles from remote sites, aU NIX-domain stream socket to 
receive articles from local processes such as nnrpd(8) and rnews(1), and aUN1X-domain datagram socket for use by 
ctlinnd(8) to direct the server to perform certain actions. It also opens the history(5) database and two log files to replace its 
standard output and standard error. If the -p flag isused, then the N NTP port is assumed to be open on the specified 
descriptor. (If this flag is used, then inna assumes it is running with the proper permissions and it does not call chown(2) on 
any files or directories it creates.) 


Oncethe files and sockets have been opened, innd waits for connections and data to be ready on its ports by using select(2) 
and non-blocking I/O. If no data is available, then it flushes its in-core data structures. T he default number of seconds to 
time out before flushing is 3e0. T his timeout may be changed by using the-+ flag. 


To limit the number of incoming N NTP connections, use the -i flag. A value of 0 suppresses this check. 


To limit the number of files that are kept open for outgoing file feeds, use the -o flag. T he default is the number of available 
descriptors minus some reserved for internal use. 


To limit the size of an article, use the -1 flag. If this flag is used, then any article bigger than size bytesisrejected. The 
default isno checking, which can also be obtained by using a value of a. 


innd rejects articles that are too old. Although this behavior can be controlled by the history database, occasionally a site 
dumps a batch of very old news back onto the network. Use the -c flag to specify a cutoff. For example -c21 rejects any 
articles that were posted more than 21 days ago. A value of @ suppresses this check. 


innd usually puts itself into the background, sets its standard output and error to log files, and disassociates itself from the 
terminal. U sing the -d flag instructs the server to not do this, whereas using the -+ flag just leaves the server running the 
foreground. The logs are usually buffered; use the -u flag to have them unbuffered. 


To start the server in a paused or throttled state (see ctlinnd(8)) use the -m flag to set theinitial running mode The 
argument should start with a single letter g, p, or t to emulate the go, pause, OF throttle commands. 
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If the -r flag is used, the server renumbers the active file as if a renumber command were sent. 


If the -s flag isused, then innd does not do any work but instead just checks the syntax of the news-feeds file. It exits with an 
error status if there are any errors; the actual errors are reported in syslog(3). 


If innd gets an NO SPC error (see intro(2)) while trying to write the active file, an article file, or the history database, it sends 
itself a throttle command. T his also happensif it gets too many I/O errors while writing to any files. 


Any subprocesses spawned by the server get a nice(2) value of 10. 


The -n flag specifies whether pausing or throttling the server should also disable future news-reading processes. A value of y 
makes news readers act as the server, a value of n allows news reading even when the server is not running. 


If the -s flag isused, then innd runsin slave mode When running asa slave, the server only accepts articles from the 
specified host, which must use the xreplic protocol extension. N ote that either the host must appear in the hosts.nntp file or 
the server must be started with the -a flag. 


By default, if ahost is not mentioned in the hosts.nntp file then the connection is handed off to nnrpa. If the -a flag is used, 
then any host can connect and transfer articles. 


If the -x flag isused, then a Xref header is added to all articles even if they are not cross-posted. 


inndstart isasmall front-end program that opens the NNTP port, sets its use' 1D and group ID to thenews maintainer, 
and then executes innd with the -p flag and a minimal secure environment. T hisis asmall, easily understood front-end 
program that can be used if a site does not want to run innd with root privileges. 


CONTROL MESSAGES 


Arriving articles that havea C ontrol header or havea Subject header that starts with the five characters cmsg are called control 
messages. Except for the cancel message, these messages are implemented by external programsin the /news/bin/control 
directory. (C ancel messages update the history database, so they must be handled internally; the cost of synching, locking, 
and then unlocking istoo high, given the number of cancel messages that are rece ved.) 


W hen acontrol message arrives, the first word of the text is converted to lowercase and used as the name of the program to 
execute if thenamed program does not exist, then a program named default is executed. 


All control programs are invoked with four parameters. T he first is the address of the person who posted the message; this is 
taken from the Sender header. If that header is empty, then it is taken from the From header. T he second parameter is the 
address to send replies to; this is taken from the Reply-To header. If that header is empty, then the poster’s address is used. 
Thethird parameter isa name under which the articleis filed, relative to the news spool directory. The fourth parameter is 
the host that sent the article, as specified on the Path line. 


The distribution of control message is also different from those of standard articles. 


Control messages are usually filed in the navsgroup named control. T hey can be filed in subgroups, however, based on the 
control message command. For example, anewgroup message is filed in control.newgroup if that group exists, otherwise it will 
be filed in control. 


Sites may explicitly have the “control” newsgroup in ther subscription list, although it is usually best to excludeit. If a 
control message is posted to a group whosename ends with the four characters .ct1, then the suffix is stripped off and what 
is left is used as the group name. For example, a cancel message posted to news. admin.ct1 will be sent to all sites that 
subscribeto control OF news.admin. newgroup and rmgroup messages receive additional special treatment. If the message is 
approved and posted to the name of the group being created or removed, then the message is sent to all sites whose 
subscription patterns would cause them to receive articles posted in that group. 


If an article is posted to a newsgroup that starts with the three letters to., it gets special treatment if the newsgroup does not 
exist in the active file. The article is filed into the newsgroup to and it is sent to the first site named after the prefix. For 
example, a posting to to.uunet iSfiled in to and sent to the site uunet. 


PROTOCOL DIFFERENCES 
innd implements the NNTP commands defined in RFC 977 with the following differences: 


innd, inndstart Eg 


m The list may be followed by an optional active, active.times, OF newsgroups argument. This common extension isnot 
fully supported; see nnrpa(8). 

mM Theauthinfo user and authinfo pass commands are implemented. T hese are based on the rerence UNIX implemen- 
tation; no other documentation is available 

m Anevcommand, mode reader, iS provided. Thiscommand causes the server to pass the connection on to nnrpd. The 
command mode query isintended for future use and is currently treated the same way. 

m Anevcommand, xreplic news.group:art[,news.group:art], is provided. Thisis similar to the inave command (the 
same reply codes are used) except for the data that follows the command word. T he data consists of entries separated by 
a single comma. Each entry consists of a newsgroup name, acolon, and an articlenumber. O nce processed, the article is 
filed in the newsgroup and articlenumbers specified in the command. 

m Anevcommand, xpath messageid, iS provided. The server responds with a 223 response and aspace-separated list of 
filenames where the article was filed. 

m Theonly othe commands implemented are head, help, ihave, quit, and stat. 


HEADER MODIFICATIONS 
innd modifies as few article headers as possible, although it could be better in this area. 
The following headers, if present, are renoved: 
D ate-R eceived 
Posted 
Posting-V ersion 
Received 
Relay-Version 


Empty headers and headers that consist of nothing but whitespace are also dropped. 

The local site's name and an exclamation point are prepended to the Path header. 

The Xref header is removed. | f the article is cross posted, a new header is generated. 

The Lines header is added if it is missing. 

innd does not rewrite incorrect headers. For example it does not replace an incorrect Lines header but rejects the article 


LOGGING 
innd reports all incoming articles in its log file. Thisisa text file with a variable number of space-separated fields in one of the 
following formats: 


mon dd hh:mm:ss.mmm + feed <Message-ID>site... 
mon dd hh:mm:ss.mmm j feed <Message-ID> site... 
mon dd hh:mm:ss.mmm c feed <Message-ID> site... 
mon dd hh:mm:ss.mmm - feed <Message-ID> reason... 


The first three fields are the date and time to millisecond resolution. The fifth fidd is the site that sent the article (based on 
the Path header), and thesixth field isthe article’s M essage-| D ; they will contain a question mark if the information is not 
available. 

The fourth field indicates whether the article was accepted. If it isa plus sign, the article was accepted. If it is the letter j, the 
article was accepted, but all of newsgroups have aj in thar active field, so the article was filed into the “junk” newsgroup. If 
the fourth fidd isthe letter c, a cancd message was accepted before the original article arrived. In all three cases, thearticle 
has been accepted and the site... fidd contains the space-separated list of sites to which the article is sent. 


If the fourth field isa minus sign, the article was rejected. The reasons for rejection include 
xs header too long 
%s wants to cancel <«s> by %s 
Article exceeds local limit of ss bytes 
Article posted in the future— %s 
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Bad %s header 

Can't write history 

Duplicate 

Duplicate %s header 

EOF in headers 

Linecount %s !=%s + %s 
Missing %s header 

No body 

No colon-spacein %s header 
No space 

Space before colon in %s header 
Too old— %s 

Unapproved for ss 

Unwanted newsgroup %s 
Unwanted distribution %s 

W hitespace in “N ewsgroups” header— %s 


W here %s, above is reolaced by more specific information. 


N ote that if an article is accepted and none of the newsgroups are valid, it islogged with both two lines, aj line and a minus 
sign line. 


innd also makes extensive reports through syslog. The first word of the log message is the name of the site if the entry is site 
specific (such as a connected message). T he first word is me if the message relates to the server itself, such as when a read error 
occurs. 


If the second word is the four letters cant, an error is bang reported. In this case, the next two words generally name the 
system call or library routine that failed and the object upon which the action was performed. The rest of the line might 
contain other information. 


In other cases, the second word attempts to summarize what change has ben made, and the rest of the line gives more 
specific information. The word internal generally indicates an internal logic error. 


HISTORY 


Written by Rich $alz (rsalze@uunet.uu.net) for InterN etN ews. 


SEE ALSO 


active(5), ctlinnd(8), dbz(3z), history(5), hosts.nntp(5), inn.conf(5), newsteeds(5), nnrpd(8), rnews(1), syslog(8) 


1nnxmit 
innxmit— Send U sené articles to aremote N NTP server. 
SYNOPSIS 
innxmit [ -A alt_spool ][-a ][-d ][-M ][-r ][-t timeout ] 
[-T timeout ][-p ][-S ] host file 
DESCRIPTION 


innxmit connects to the N N TP server at the specified host and sends it the articles specified in the batchfile named file It is 
usually invoked by a script run out of cron(8) that uses shlock(1) to lock the hostname, followed by actlinna(8) command to 
flush the batchfile. 


ipcrm Ea 


innxmit usually blocks until the connection is made. T o specify a timeout on how long to try to make the connection, use the 
-t flag. T 0 specify the total amount of time that should be allowed for article transfers, use the -T flag. T he default is to wait 
until an I/O error occurs or all the articles have been transferred. If the -T flag is used, the time is checked just before an 
article is started; it does not abort a transfer that isin progress. Both values are measured in seconds. 


If the file is not an absolute pathname, it is taken relative to the /news/spool/out.going directory. It is usually written by 
specifying the wnm flags in the newsfeeds(5) file Each linein the batchfile should bein one of the following formats: 
filename Message-ID 


filename 


The filename field names the article to be sent. If it isnot an absolute pathname it is taken relative to the news spool 
directory, /news/spool. If the Message -10 field isnot specified, it is obtained by scanning the article The filename and 
Message-Id fields are separated by a space. 


If a communication error such aS a write(2) failure occurs, innxmit stops sending and rewrites the batchfile to contain the 
current article and any other unsent articles. 


If the renote server sends an unexpected reply code, innxmit requeues the article and proceeds. Use the -r flag if the article 
should not be requeued. 


Upon exit, innxmit reports transfer and CPU usage statistics via sys1og(3). If the -v flag is used, they are also printed on the 
standard output. If all articles were sent successfully, innxmit ranoves the batchfile otherwise, it rewrites it to contain the list 
of unsent articles. If no articles were sent or rejected, the file is left untouched. T his can cause the batchfile to grow 
excessively large if many articles have been expired and there are communication problems. T 0 always rewrite the batchfile, 
use the -a flag. I f the -p flag is given, then no connection is made and the batchfile is purged of entries that refer to files that 
no longer exist. T his implies the -a flag. 


If the -s flag isgiven, then innxmit offers articles to the specified host using the xreplic protocol extension described in 
innd(8). To use this flag, the input file must contain the history data (commas are transliterated to spaces by the server). For 
this flag to be used, the input must contain the necessary history entries. Thisis usually done by setting up awnr entry in the 
newsfeeds file 


Use the -d flag to print debugging information on standard error. T his shows the protocol transactions between innxmit and 
the NNTP server on the renote host. 


If the -m flag is used, innxmit scans an article's headers before sendingit. If the article appears to bea MIM E article that isnot 
in seven-bit format, thearticle is sent in “quoted-printable” form. 


The -a flag may be used to specify an alternate spool directory to use if the article is not found; thisis usually an N FS- 
mounted spool directory of a master server with longer expiration times. 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


ctlinnd(8), innd(8), newsteeds(5), shlock(1) 


ipcerm 

iperm— Remove ipc facilities. 
SYNOPSIS 

ipcrm [ shm |; msg ; sem ] id 
DESCRIPTION 


iperm removes the resource specified by id. 
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SEE ALSO 
ipces(8) 


AUTHOR 


Krishna Balasubramanian (balasub@cis.ohio-state.edu) 
Linux 0.99, 9 October 1993 


ipcs 
ipcs— Provide information on ipc facilities. 


SYNOPSIS 
ipcs [ -asmq ] [ -tclup ] 
ipcs [ -smq ] -iid 
ipcs -h 
DESCRIPTION 
ipes provides information on the ipc facilities for which the calling process has read access. 
The -i option allows a specific resource i ¢ to be specified. O nly information on thisi d is printed. 
Resources may be specified as follows: 


-m Shared memory segments 
-q M essage queues 

-s Semaphore arrays 

-a All (this is the default) 


The output format may be specified as follows: 





-t Time 

-p PID 

-C Creator 

“1 Limits 

-U Summary 
SEE ALSO 

iperm(8) 
AUTHOR 


Krishna Balasubramanian (balasub@cis.ohio-state.edu) 
Linux 0.99, 9 October 1993 


kbdrate 


kbdrate— Reset the keyboard repeat rate and dday time. 
SYNOPSIS 


kbdrate [ -s ] [ -r rate ][-d delay ] 


klogd Eg 
DESCRIPTION 


kbdrate is used to change theIBM keyboard repeat rate and delay time. T he delay is the amount of time that a key must be 
pressed before it starts to repeat. U sing kbdrate without any options resets the rate to 10.9 characters per second (cps) and 
the dday to 250 milliseconds (ms). These arethe|IBM defaults. 


OPTIONS 
-s Silent. N o messages are printed. 
-r rate Change the keyboard repeat rate to rate cps. The allowable rangeisfrom 2.0 to 30.0 cps. Only certain 
specific values are possible, and the program selects the nearest possible value to the one specified. The 
possible values are given, in characters per second, as follows: 2.0, 2.1, 2.3, 2.5, 2.7, 3.0, 3.3, 3.7, 4.0, 4.3, 
4.6, 5.0, 5.5, 6.0, 6.7, 7.5, 8.0, 8.6, 9.2, 10.0, 10.9, 12.0, 13.3, 15.0, 16.0, 17.1, 18.5, 20.0, 21.8, 24.0, 
26.7, 30.0. 
-d delay Change the dday to del ay milliseconds. T he allowable range is from 250 to 1000 ms, but the only possible 
values (based on hardware restrictions) are 250 ms, 500 ms, 750 ms, and 1000 ms. 
BUGS 


N ot all keyboards support all rates. 

N ot all keyboards have the rates mapped in the same way. 

Setting the repeat rate on the Gateway AnyK ey keyboard does not work. If someone with a G ateway figures out how to 
program the keyboard, please send mail to faith@cs.unc. edu. 


FILES 


/etc/rc.local 
/dev/port 


AUTHOR 


Rik Faith (faith@cs.unc. edu) 
Linux 1.1.19, 22 June1994 


klogd 


klogd— Kernel log daenon. 


SYNOPSIS 
klogd -c [n] -d -f [fname] -os 
DESCRIPTION 
klogd isa system daemon that intercepts and logs Linux kernal messages. 
OPTIONS 
-c Sets the default log levd of console messages to [n]. 
-d Enables debugging mode This will generate a lot of output to stderr. 
-f Logs messages to the specified filename rather than to the sysiog facility. 


-0 Execute in one-shot mode. This causes k1ogd to read and log all the messages that are found in the kernel 
message buffers. After a single read and log cycle, the daemon exits. 


“s Force klogd to use the system call interface to the kernel message buffers. 
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OVERVIEW 


The functionality of k1oga has been typically incorporated into other versions of syslogd, but this seams to be a poor place 
for it. In the modern Linux kernel, a number of kernel messaging issues such as sourcing and prioritization must be 
addressed. Incorporating kernd logging into a separate process appears to offer a cleaner separation of services. 


In Linux, there are two potential sources of kernel log information: the /proc filesystem and the syscall (sys_syslog) 
interface, although ultimately they are one and the same k1ogd is designed to choose whichever source of information isthe 
most appropriate. It does this by first checking for the presence of a mounted /proc filesystem. If this is found, the 
/proc/kmsg file is used as the source of kernd log information. If the proc filesystan is not mounted, klogd uses a system call 
to obtain kernel messages. The command-line switch (-s) can be used to force klogd to use the system call interface as its 
messaging source. 


If kernel messages are directed through the syslogd daemon, theklogd daemon, as of version 1.1, has the ability to properly 
prioritize kernel messages. Prioritization of the kernd messages was added at approximately the p113 level of the kernd. The 
raw kernd messages are of the form: 


<[O-7]>Something said by the kernel. 


The priority of the kernel message is encoded as a single numeric digit enclosed inside the <> pair. T he definitions of these 
values is given in the Kernel include file kerne1.h. W hen a message is received from the kernel, the klogd daemon reads this 
priority level and assigns the appropriate priority leva to the syslog message. If file output (-*) is used, the prioritization 
sequence is left prepended to the kernel message. 


The klogd daemon also allows the ability to alter the presentation of kernd messages to the system console C onsequent with 
the prioritization of kernd messages was the inclusion of default messaging levels for the kernel. In a stock kernel, the default 
consolelog level is set to 7. Any messages with a priority led numerically lower than 7 (higher priority) appear on the 
console. 


M essages of priority level 7 are considered to be debug messages and do not appear on the console. M any administrators, 
particularly in a multi-user environment, prefer that all kernel messages be handled by k1ogd and either directed to a file or 
to the syslogd daemon. T his prevents nuisance messages such as line printer out of paper or disk change detected from 
cluttering the console 

By default, the klogd daemon executes a system call to inhibit all kane’ messages (except for panics) from being displayed on 
the console The -c switch can be used to alter this behavior. T he argument given to the -c switch specifies the priority level 
of messages that are directed to the console. N ote that messages of a priority value lower than the indicated number are 
directed to the console 

For example, to have the kernd display all messages with a priority level of 3 (KERN ERR) or more severe, the following 
command is executed: 

klogd -c 4 

The definitions of thenumeric values for kerndl messages are given in the file kerne1.h, which can befound in the 


/usr/include/ linux directory if the kernel sources are installed. T hese values parallel the syslog priority values, which are 
defined in the file sysiog.h, found in the /usr/include/sys subdirectory. 


The klogd daemon can also be used in aone-shot mode for reading the kernel message buffers. O ne-shot mode is selected by 
specifying the -o switch on the command line. O utput is directed to either the syslogd daemon or to an alternate file 
specified by the -+ switch. 


For example, to read all the kernel messages after a system boot and record them in a file called krn1.msg, the following 
command is given: 


klogd -o -f ./krnl.msg 


SIGNAL HANDLING 


The klogd daemon responds to six signals: SIGHUP, SIGINT, SIGKILL, SIGTERM, SIGTSTP, aNd SIGCONT. T h@ SIGINT, SIGKILL, 
SIGTERM, and SIGHUP signals cause the daemon to close its kernel log sources and terminate gracefully. 


Ipc 1317 


The stetstp and siecont signals are used to start and stop kernd logging. U pon receipt of a statstp signal, the daemon closes 
its log sources and spinsin an idle loop. Subsequent receipt of asraconT signal causes the daemon to go through its 
initialization sequence and rechoose an input source. U sing siastop and siccont in combination, the kernel log input can be 
rechose without stopping and restarting the daemon. For example, if the /proc filesystem is to be unmounted, the following 
command sequence should be used: 


# kill -TSTP pid 
# umount /proc 
# kill -CONT pid 


N otations will be madein the system logs with Loa 1nFo priority documenting the start/stop of logging. 
FILES 


/proc/kmsg 


BUGS 


Probably numerous. W ell-formed context diffs appreciated. 


AUTHOR 
Dr. Greg W ettstein (gregswind.uucp@plains .nodak.edu), Enjdlic Systans D evdopment, Oncology Research D ivision 
Computing Facility, Roger M aris Cancer Center, Fargo, ND 58122. 


Vergon 1.1, 28 January 1994 


lpc 


lpe— Line printer control program. 


SYNOPSIS 


lpc [command [argument ...]] 


DESCRIPTION 


lpe isused by the system administrator to control the operation of the line printer system. For each line printer configured in 
/etc/printcap, lpc may be used to 


m Disable or nablea printer 

m Disable or enablea printer's spooling queue 

m Rearrange the order of jobs in a spooling queue 

m Find the status of printers and thar associated spooling queues and printer daanons 


Without any arguments, 1pc prompts for commands from the standard input. If arguments are supplied, 1pc interprets the 
first argument as a command and the renaining arguments as parameters to the command. T he standard input may be 
redirected, causing 1pc to read commands from file Commands may be abbreviated; the following is the list of recognized 
commands: 


2? [ command ... Jhelp [ command ... ] Print ashort description of each command specified in the argument 
list or, if no arguments are given, a list of the recognized commands. 
Ic abort No all - printer Terminate an active spooling daanon on the local host immediately 


and then disable printing (preventing new daemons from being 
started by lpr) for the specified printers. 

clean No all - printer Remove any temporary files, data files, and control files that cannot 
be printed (that is, they do not form acomplee printer job) from the 
specified printer queues on the local machine 

disable No all - printer Turn the specified printer queues off. T his prevents new printer jobs 
from being entered into the queue by pr. 
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Ic down No all - printer message ... Turn the specified printer queue off, disable printing, and put message 
in the printer status file. T he message doesn’t need to be quoted; the 
remaining arguments are treated like echo(1). T his is usually used to 
take a printer down and let others know why 1pq(1) indicates the 
printer isdown and print the status message. 


enable No all -- printer Enable spooling on the local queue for the listed printers. T his allows 
ipr(1) to put new jobsin the spool queue. 

exit, quit Exit from ipe. 

restart all - printer Attempt to start a new printer daemon. This is useful when some 


abnormal condition causes the daenon to die unexpectedly leaving 
jobs in the queue. 1pq reports that there isno daanon present when 
this condition occurs. | f the user is the super-user, try to abort the 
current daemon first (that is, kill and restart a stuck daemon). 


start all - printer Enable printing and start a spooling daemon for the listed printers. 
status No all - printer Display the status of daemons and queues on thelocal machine 
stop all - printer Stop a spooling daemon after the current job completes and disable 
printing. 
topg printer [ jobnum... ] [ user ... ] Place the jobs in the order listed at the top of the printer queue. 
up all - printer Enable everything and start a new printer daemon. U ndoes the effects 
of down. 
FILES 
/etc/printcap printer description file 
/var/spool/* spool directories 
/var/spool/*/lock lock file for queue control 
SEE ALSO 
1pd(8), 1pr(1), 1pq(1), 1prm(1), printcap(5) 
DIAGNOSTICS 
2Ambiguous command Abbreviation matches more than one command. 
?Invalid command No match was found. 
?Privileged command Command can be executed by root only. 
HISTORY 


The 1pe command appeared in BSD 4.2. 
BSD 4.2, 16 March 1991 


lpd 


ipd— Line printer spooler daemon. 


SYNOPSIS 
Ipd [-1] [port #] 
DESCRIPTION 


1pd istheline printer daemon (spool area handler) and is usually invoked at boot time from the rc(8) file It makes a single 
pass through the printcap(5) file to find out about the existing printers and prints any files left after a crash. It then uses the 
system calls 1isten(2) and accept(2) to receive requests to print files in the queue, transfer files to the spooling area, display 


the queue or remove jobs from the queue In each case, it forks a child to handle the request so the parent can continue to 
listen for more requests. 


Available options: 


“1 The -1 flag causes 1pa to log valid requests received from the network. T his can be useful for 
debugging purposes. 
port# The Internet port number used to rendezvous with other processes is usually obtained with 


getservbyname(3) but can be changed with the port # argument. 


Access control is provided by two means. First, all requests must come from one of the machines listed in the file /etc/ 
hosts.equiv Or /etc/hosts.1pd. Second, if the rs capability is specified in the printcap entry for the printer being accessed, 
lpr requests are only honored for those users with accounts on the machine with the printer. 

The file minfree in each spool directory contains the number of disk blocks to leave free so that the line printer queue won't 
completdy fill the disk. The minfree file can be edited with your favorite text editor. 

The daemon begins processing files after it has successfully set the lock for exclusive access (described later) and scans the 
spool directory for files beginning with ct. Linesin each cf file specify files to be printed or non-printing actions to be 
performed. Each such line begins with a key character to specify what to do with the renainder of the line: 

J Job name String to be used for the job name on the burst page. 

C Classification. String to be used for the classification line on the burst page. 


L Literal. Theline contains identification info from the password file and causes the banner page 
to be printed. 


Title. String to be used as the title for pr(1). 

H ost name N ame of the machine where ipr was invoked. 

Person. Login name of the person who invoked 1pr. T his is used to verify ownership by lprm. 
Send mail to the specified user when the current print job completes. 
Formatted file N ame of afile to print which is already formatted. 

Like but passes control characters and does not make page breaks. 

Name of a file to print using pr(1) as a filter. 

T roff file The file contains trof#(1) output (cat phototypesetter commands). 
D itroff file. T he file contains device independent troff output. 

DVI file. The file contains T ex | output D V1 format from Standford. 

Graph file. The file contains data produced by p1ot(3). 

Cifplot file Thefile contains data produced by cifplot. 

The file contains a raster image. 

The file contains text data with FORTRAN carriage control characters. 
Troff font R. N aneof the font file to use instead of the default. 

T roff font |. N ame of thefont file to use instead of the default. 

T roff font B. N ame of the font file to use instead of the default. 

T roff font S. N ame of the font file to use instead of the default. 

W idth. Changes the page width (in characters) used by pr(1) and the text filters. 
Indent. The number of characters to indent the output by (in ASCII). 
Unlink. Name of file to remove upon completion of printing. 


Fileame. The name of the file that is being printed or a blank for the standard input (when lpr 
isinvoked in a pipeline). 
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If a file cannot be opened, a message is logged via sys1og(3) using the Loa Lpr facility. 1pa tries up to 20 times to reopen afile 
it expects to be there after which it skips the file to be printed. 
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lpd USES flock(2) to provide exclusive access to the lock file and to prevent multiple daemons from becoming active 
simultaneously. If the daemon should be killed or die unexpectedly, the lock file need not be removed. The lock file is kept 
in areadable ASCII form and contains two lines. T he first is the process!D of the daemon and the second is the control 
filename of the current job being printed. T he second lineis updated to reflect the current status of 1pd for the programs 
1pq(1) and 1prm(1). 


FILES 

/etc/printcap Printer description file 

/var/spool/* Spool directories 

/var/spool/*/minfree Minimum free space to leave 

/dev/1p* Line printer devices 

/dev/printer Socket for local requests 

/etc/hosts.equiv Lists machine names allowed printer access 

/etc/hosts.1pd Lists machine names allowed printer access but not under same administrative control 
SEE ALSO 


1pe(8), pac(1), 1pr(1), 1pq(1), 1prm(1), systog(3), printcap(5) 
4.2 BSD Line Printer Spooler M anual 
HISTORY 
An 1pa daemon appeared in Version 6, AT&T UNIX. 
BSD 4.2, 16 March 1991 


MAKEDEV 


MAKEDEV— C reates and maintains filesystem device entries. 


SYNOPSIS 


MAKEDEV [ -vcdnhv ] device or device-group names 


DESCRIPTION 


MAKEDEV is used to maintain the special filesystem entries found in /dev. It creates, or optionally renoves, one or more device 
entries. The names and device numbers are defined in the devinfo file (q.v.); site-specific configuration is found in the file 
MAKEDEV. cfg. MAKEDEV itself has no knowledge of device information. 


OPTIONS 
“V Verbose mode print out exactly what’s bang done 
c Create; create the specified devices (default). 
-d Delete; remove the specified devices instead of creating them. 
-n Do nothing; only print what would be done | mplies -v as well. 
-h Print a usage message. 
-V Print the version string. 


The following targets are special: 


update Run makeDev in update mode. T his reads the list of devices currently available from 
/proc/devices and updates all entriesin /dev to match the device numbers found there. 
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local Run makevev to create local devices. This option is obsolete and just prints a warning message. 
Use devinfo.local and makedev.cfg to achieve the same results. 


FILES 
/etc/devinfo D evice information 
/usr/local/etc/devinfo. local Local device information 
/etc/devinfo. local Alternate location for local device information 
/etc/makedev.cfg Configuration file 
MAKEDEV. cache Cached data for update 
/proc/devices The kernel’s list of current devices 
AUTHOR 


David A. Holland (dholland@husc .harvard.edu). Based on the older makepev shal script written by Nick H olloway. Addi- 
tional ideas were contributed by Rik Faith. 


NOTES 


The Latr(1) parser generator used to build makedev.c from makedev.syn isa commercial product. You won't be ableto doa 
complete rebuild unless you have it. 


SEE ALSO 


devinfo(5), makedev.cfg(5) 
Verson 1.5, M arch 1995 


MAKEDEV 


MAKEDEV— C reates devices. 


SYNOPSIS 


cd dev; ./MAKEDEV -V 
cd dev; ./MAKEDEV [ - 
cd dev; ./MAKEDEV [ - 


DESCRIPTION 


MAKEDEV iS a script that creates the devices in /dev used to interface with drivers in the kernel. 


device ... 


N ote that programs giving the error ENOENT: No such file or directory usually means that the device fileis missing, whereas 
ENODEV: No such device usually means the kernel does not have the driver configured or loaded. 


OPTIONS 

Vv Print out version (actually RCS version information) and exit. 

-n Do not actually update the devices; just print theactions that would be performed. 

-d D elete the devices. The main use for this flag is by makevev itself. 

“V Be verbose. Print out the actions as they are performed. Thisis the same output as produced by -n. 
CUSTOMIZATION 


Because there is currently no standardization in what names are used for system users and groups, it is possible that you 
might need to modify makepev to reflect your site’s settings. N ear the top of the file is a mapping from device type to user, 
group, and permissions. (For example, all CD-ROM devices are set from the $cdrom variable.) If you want to change the 
defaults, thisis the section to edit. 


Eg Part VIII: Administration and Privileged Commands 


DEVICES 


General O ptions 


update 


generic 


std 


local 


Virtual T eminals 


This only works on kernds that have /proc/interrupts (introduced during 1.1.x). This fileis 
scanned to see what devices are currently configured into the kernd, and thisiscompared with 
the previous settings stored in the file called pevices. D evices that are new since then or havea 
different major number are created, and those that are no longer configured are deleted. 
Create a generic subset of devices. T his is the standard devices, plus floppy drives, various hard 
drives, pseudo-terminals, console devices, basic serial devices, busmice, and printer ports. 
Standard devices. T hese are mem, access to physical memory; kmem, accessto kernd virtual 
memory; nu1l1, null device (infinite sink); port, accessto I/O ports; zero, null byte source 
(infinite source); core, symlink to /proc/kcore (for kernel debugging); full, always returns 
ENOSPACE On write; ram, ramdisk; tty, to access the controlling tty of a process. 


This simply runs MAKEDEV. local. This is a script that can create any local devices. 








console This creates the devices associated with the console T hisis the virtual terminals ttyx, where x 
can be from @ though 63. T he device ttya is the currently active vt and is also known as console 
For each vt, there are two devices, vesx and vcsax, which are used to generate scren-dumps of 
the vt (the vesx isjust thetext and vesax includes the attributes). 

Serial D evices 

ttyS{0..63} Seial ports and corresponding dial-out device. For device ttysx, there is also the device cuax, 
which is used to dial out with. This can avoid the nead for cooperative locks in simple 
situations. 

cyclades Did-in and dial-out devices for the cyclades intelligent 1/O serial card. The dial in deviceis 


Pseudo T erminals 


ttycx and the corresponding dial-out device is cubx. By default, devices for 7 lines are created, 
but this can be changed to 15 by removing the comment. 





pty[p-s] 


Parallel Ports 


Each possible argument will create a bank of 16 master and slave pairs. T he current kernel (1.2) 
is limited to 64 such pairs. The master pseudo-terminals are pty[p-s][@-9a-f] and theslaves are 
tty[p-s][0-9a-f]. 














lp Standard parallel ports. The devices are created 1p0, 1p1, and 1p2. These correspond to ports at 
Ox3bc, 0x378, and 0x278. H ence, on some machines, the first printer port may actually be 1p1. 

par Alternative to 1p. Ports are named parx instead of ipx. 

BusM ice 

busmice The various bus mice devices. T his creates the following devices: logimouse (Logitech bus 
mouse), psmouse (PS/2-style mouse), msmouse (M icrosoft Inport bus mouse), atimouse (ATI XL 
bus mouse) and jmouse (J -mouse). 

Joystick D evices 

js Joystick. Creates jso and jsi. 

Disk Devices 

fd[0-7] Floppy disk devices. The device fax is the device that autodetects the format, and the additional 


devices are fixed format (whose size is indicated in the name). The other devices are named as 
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fdxtn. Thesingle letter L identifies the type of floppy disk (d =5.25" DD, h =5.25" HD, 
d=3.5"DD,4 =3.5"HD, € =3.5" ED). Thenumber n represents the capacity of that format 
in KB. Thus the standard formats are fdx d360, fdxh1200, fdxD720, fdxH1440, and fdx E2880. 

For more information, see Alain K naff’s fautils pack-age. 

D evices faa* through fd3* are floppy disks on the first controller, and devices fa4* through fa7* 
are floppy disks on the second controller. 





hd[a-d] AT hard disks. The device hdx provides access to the whole disk, with the partitions being 
hdx [@-20]. T he four primary partitions are hax 1 through hax 4, with the logical partitions being 
numbered from haxs though hax 20. (A primary partition can be made into an extended 
partition, which can hold four logical partitions). By default, only the devices for four logical 
partitions are made. The others can be made by uncommenting them. 
Drives hda and hdb are the two on the first controller. If using thenew IDE driver (rather than 
theold HD driver), then hdc and had are the two drives on the secondary controller. T hese 
devices can also be used to access IDE CD-ROM Sif using the new IDE driver. 

xd[a-d] XT hard disks. Partitions are the same as IDE disks. 

sd[a-h] SCSI hard disks. The partitions are smilar to the IDE disks, but thereis alimit of 11 logical 
partitions (sdx 5 through sdx 15). T hisis to allow 8 SCSI disks. 

loop Loopback disk devices. T hese allow you to use a regular file as a block device. T his means that 
images of filesystems can be mounted and used as normal. This creates 8 devices loopa through 
loop7. 

T ape D evices 

st[0-7] SCSI tapes. T his creates the rewinding tape device stx and the non-rewinding tape device nstx. 

qic QIC-80 tapes. The devices created are rmt8, rmt16, tape-d, and tape-reset. 

ftape Floppy driver tapes (Q|1C-117). There are four methods of access depending on the floppy tape 
drive. For each of the access methods 0, 1, 2, and 3, the devices rftx (rewinding) and nrttx 
(non-rewinding) are created. For compatibility, devices ftape and nftape are symlinks to rfto 
and nrfto. 

CD-ROM Devices 

scd[0-7] SCSI CD players. 

sonycd Sony CDU-31A CD player. 

med Mitsumi CD player. 

cdu535 Sony CDU-535 CD player. 

lmscd LM S/PhilipsCD player. 


sbpcd{,1,2,3} 


SoundBlaster CD player. The kernel is capable of supporting 16 CD-ROMs, each of which is 
accessed aS sbpcd[0-9a-f]. T hese are assigned in groups of four to each controller. sbpcd isa 
symlink to sbpcdo. 








Scanner 

logiscan Logitech ScanM an32 and ScanM an 256. 

m1@5scan M ustek M 105 H andscanne. 

ac4096 A4T ek Color H andscanner. 

Audio 

audio This creates the audio devices used by the sound driver. These include mixer, sequencer, dsp, 
and audio. 

pcaudio Devices for the PC Speaker sound driver. T hese are pemixer, pxsp, and pcaudio. 
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M iscdlaneous 





sg Generic SCS! devices. T he devices created aresga through sg7. These allow arbitrary commands 
to be sent to any SCSI device This allows for querying information about the device or 
controlling SCSI devices that are not one of disk, tape, or CD-ROM (for example, a scanner or 
writableCD-ROM). 

fd To allow an arbitrary program to be fed input from file descriptor x, use /dev/fd/x asthe 
filename. This also creates BR/dev/stdin, BR/dev/stdout, and BR/dev/stderr. (N ote that these are 
just symlinks into /proc/self/fd.) 





ibes2 Devices (and symlinks) needed by the |BCS2 enulation. 
apm Devices for power management. 
def Driver for D CF-77 radio clock. 
helloworld Kernd modules denonstration device See the modules source. 
N etwork devices Linux used to have devicesin /dev for controlling network devices, but that is no longer the 
case. To see what network devices are known by the kernal, look at /proc/net/dev. 
SEE ALSO 
Linux Allocated D evices, maintained by H. Peter Anvin (Peter.Anvin@linux.org) 
AUTHOR 
N ick H olloway 


Linux, 14 August 1994 


mke2ts 


mke2#s— Create a Linux second extended filesystem. 


SYNOPSIS 


mke2fs [ -c | -l filename ] [ -b block-size ] [ -f fragment-size ] 
[ -i bytes-per-inode ] [ -mreserved-blocks-percentage ] [ -q ][-v ][-S ] 
device [ blocks-count ] 


DESCRIPTION 
mke2fs iS used to create a Linux second extended filesystem on a device (usually a disk partition). device isthe special file 
corresponding to the device (such as /dev/hdXx). bl ocks- count isthe number of blocks on the device. If omitted, mke2fs 
automatically figures the filesystem size. 





OPTIONS 

-b block-size Specify the size of blocks in bytes. 

-C Check the device for bad blocks before creating the filesystem using a fast read-only 
test. 

-f fragment-size Specify the size of fragments in bytes. 

-i bytes-per-inode Specify the bytes/inode ratio. mke2fs creates an inode for every bytes-per-inode bytes 
of space on the disk. T his value defaults to 4096 bytes. byt es-per-inode must beat 
least 1024, 

-1 filename Read the bad blocks list from filename. 

-mreserved- blocks-percentage Specify the percentage of reserved blocks for the super-user. T his value defaults to 5 
percent. 

-q Quiet execution. U seful if mke2ts isrun in a script. 


“Vv Verbose execution. 


mkfs [| 


-S W rite superblock and group descriptors only. Thisis useful if all the superblock and 
backup superblocks are corrupted and a last-ditch recovery method is desired. It 
Causes mke2fs to rdnitialize the superblock and group descriptors while not touching 
the inode table and the block and inode bitmaps. T he e2fsck program should be run 
immediately after this option is used, and there is no guarantee that any data will be 


salvageable. 
AUTHOR 
This version of mke2fs has been written by Theodore T’so (tytso@mit.edu). 
BUGS 


mke2fs accepts the -¢ option but currently ignores it because the second extended filesystem does not support fragments yet. 
There may be some other bugs. Please report then to the author. 
AVAILABILITY 


mke2fs iS available for anonymous FT P from ftp.ibp.fr and tsx-11.mit.edu iN /pub/linux/packages/ext2fs. 


SEE ALSO 


badblocks(8), dumpe2fs(8), e2fsck(8), tune2ts(8) 
Vergon 0.5b, N ovenber 1994 
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mkfs— Build a Linux filesystem. 
SYNOPSIS 


mkfs [ -V ][-t fstype ][fs-options ] filesys [ blocks ] 


DESCRIPTION 


mkfs iS used to build a Linux filesystem on a device usually a hard disk partition. fil esys is either the device name (such as / 
dev/hdat, /dev/sdb2) or the mount point (such as /, /usr, /home) for the filesystem. bi ocks isthe number of blocks to be used 
for the filesystem. 


The exit code returned by mkfs is@ on success and 1 on failure. 


In actuality, mkfs is simply a front end for the various filesystem builders (mkfs. fstype) available under Linux. The filesystem- 
specific builder is searched for in /etc/fs first, then in /etc, and finally in the directories listed in the PATH environment 
variable. Please see the filesystem-specific builder manual pages for further details. 


OPTIONS 


-V Produce verbose output, including all filesystem-specific commands that are executed. 
Specifying this option more than once inhibits execution of any filesystem-specific commands. 
Thisis really only useful for testing. 

-tfstype Specifies the type of filesystem to be built. If not specified, the type is deduced by searching for 
filesys iN /etc/fstab and using the corresponding entry. If the type cannot be deduced, the 
default filesystem type (currently minix) is used. 


fs-options Filesystem-specific options to be passed to the real filesystem builder. Although not guaranteed, 
the following options are supported by most filesystem builders. 

-c Check the device for bad blocks before building the filesystem. 

-lfilename Read the bad blocks list from filename. 


“V Produce verbose output. 
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BUGS 


All generic options must precede and not be combined with filesysten-specific options. Some filesystem-specific programs do 
not support the -v (verbose) option nor return meaningful exit codes. Also, some filesystem-specific programs do not 
automatically detect the device size and require the blocks parameter to be specified. 


AUTHORS 


D avid Engel (davideods.com), Fred N. van Kempen (waltje@uwalt.nl.mugnet.org), and Ron Sommeiing (sommel@sci.kun.n1). 
The manual page was shamelessly adapted from Remy Card's version for the ext2 filesysten. 


SEE ALSO 
fsck(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8) 
Verson 1.9, June1995 
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kts— M ake a Linux MIN IX filesystem. 
SYNOPSIS 
mkfs [ -c ] [ -nnamelength ] [ -i inodecount ] device size-in-blocks 
mkfs [ -1 filename ] device size-in-blocks 
DESCRIPTION 
mkfs Creates a Linux MIN IX filesystem on a device (usually a disk partition). 


The device is usually of the following form: 
/dev/hda[1-8] 
/dev/hdb[ 1-8] 
/dev/sda[1-8] 
/dev/sdb[1-8] 


Thesize-in- blocks parameter isthedesired size of the filesystem in blocks. This information can be determined from the 
fdisk(8) program. O nly block counts strictly greater than 10 and strictly less than 65,536 are allowed. 


OPTIONS 
-c Check the device for bad blocks before creating the filesystem. If any are found, the count is 
printed. 
-nnamelength Specify the maximum length of filenames. N 0 space is allowed between the -n and the 
namel ength. Currently, the only allowable values are 14 and 30. 30 is the default. 
-i inodecount Specify the number of inodes for the filesystem. 
-1 filename Read the bad blocks list from filename. Thefile has one bad block number per line. The count 
of bad blocks read is printed. 
EXIT CODES 
The exit code returned by mkfs.minix is one of the following: 
0 No errors 
8 Operational error 
16 U sage or syntax error 
SEE ALSO 


fsck(8), mkefs(8), efsck(8), reboot(8) 


mklost-+found 
AUTHOR 


Linus T orvalds (torvalds@cs.helsinki.fi). Error code values by Rik Faith (faithe@cs.unc. edu). Inode request feature by Scott 
H eavner (sdh@po.cwru.edu). Support for the filesystem valid flag by Dr. W ettstein (greg%wind.uucp@plains.nodak.edu). 


Check to prevent mkfs of mounted filesystem and boot sector clearing by Danid Quinlan (quinlan@yggdrasil.com). 
Linux 0.99, 10 January 1994 


mklostt+found 


mklost+found— C reate alost-found directory on amounted Linux second extended filesystem. 


SYNOPSIS 


mklost+found 


DESCRIPTION 


mklost+found is used to create alost+found directory in the current working directory on a Linux second extended filesystem. 
mklost+found pre-allocates disk blocks to the directory to make it usable by e2fsck. 


OPTIONS 


There arenone 


AUTHOR 


mklost+found was written by Reny Card (cardemasi. ibp.fr), the developer and maintainer of the ext2 fs. 


BUGS 


There are none :-) 


AVAILABILITY 


mklost+found is available for anonymous FT P from ftp. ibp.fr and tsx-11.mit.edu iN /pub/linux/packages/ext2fs. 


SEE ALSO 


e2fsck(8), mke2ts(8) 








Vergon 0.5b, N ovenber 1994 
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mkswap— Set up a Linux swap area. 


SYNOPSIS 


mkswap [ -c ] device [size-in- blocks] 


DESCRIPTION 
mkswap sets up a Linux swap area on adeviceor in afile 
The device is usually of the following form: 


/dev/hda[1-8] 
/dev/hdb[1-8] 
/dev/sda[1-8] 
/dev/sdb[1-8] 
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Thesize-in- blocks parameter isthe desired size of the filesystem in blocks. T his information is determined automatically by 
mkswap if it isomitted. Block counts are rounded down so that the total size is an integer multiple of the machine's page size. 
Only block counts in the range MINCOUNT. .mAXCOUNT are allowed. If the block count exceeds the maxcounT, it is truncated to 
that value and a warning message is issued. 

The mINcount and maxcount values for a swap area are 


MINCOUNT = 10 * pAGE_size / 1024 
MAXCOUNT =(PAGE_SIZE-10)*8 *PpaGe_size / 1024 
For example, on amachine with 4KB pages (such as x86), we get 


MINCOUNT = 10 * 4096 / 1024 =40 
MAXCOUNT = (4096 - 10) * 8 * 4096 / 1024 =130752 





Aseach block is 1K B, the swap area in this example could havea sizethat is anywhere in therange from 40K B to 
127.6875M B. 


If you don’t know the page size that your machine uses, you may be able to look it up with cat /proc/cpuinfo. 


The reason for the limit on maxcounT is that a single page is used to hold the swap bitmap at the start of the swap area, where 
each bit represents a single page. T he reason for the -10, is that the signature is swap-space - 10 characters. 


To s& up a swap file it is necessary to create that file before running mkswap. A sequence of commands similar to the 
following is reasonable for this purpose: 


# dd if=/dev/zero of=swapfile bs=1024 count=8192 
# mkswap swapfile 8192 

# sync 

# swapon swapfile 


N ote that a swap file must not contain any holes (so using cp(1) to create the file is not acceptable). 


OPTIONS 
-c Check the device for bad blocks before creating the filesystem. If any are found, the count 
is printed. This option is meant to be used for swap partitions only and should not be 
used for regular files! To make sure that regular files do not contain bad blocks, the 
partition that contains the regular file should have bem created with mkfs -c. 
SEE ALSO 
fsck(8), mkfs(8), fdisk(8) 
AUTHOR 


LinusT orvalds (torvalds@cs. helsinki. fi) 
Linux 1.0, 8 February 1995 


mount, umount 


mount, umount— M ount and dismount filesystems. 


SYNOPSIS 
mount [-afrwuvn] [-t vfstype] 
mount [-frwuvn] [-o remount [,...]] special | node 
mount [-frwun] [-t vfstype] [-o options] special | node 


umount [-an] [-t vfstype] 
umount special | node 


mount, unmount 
DESCRIPTION 


The mount command calls the mount(2) system call to prepare and graft a special device onto the filesystem tree at the point 
node. If either special Or node arenot provided, the appropriate information is taken from the fstab(5) file. T he special 
keyword none can be used instead of a path or node specification. T his is useful when mounting the proc filesystem. 


The systan maintains a list of currently mounted filesystems. If no arguments are given to mount, this list is printed. 
O ptions available for the mount command: 


-f Causes everything to be done except for the actual system call; if it's not obvious, this 
“fakes” mounting the filesystem. T his option is useful in conjunction with the -v flag to 
determine what the mount command is trying to do. 

-0 O ptions are specified with a -o flag followed by a comma-separated string of options. 

N ote that many of these options are only useful when they appear in the /etc/fstab file. 
The following options apply to any filesystem that is being mounted: 


async All 1/0 to the filesystem should be done asynchronously. 

auto Can be mounted with the -a option. 

defaults Use default options: rw, suid, dev, exec, auto, nouser, and async. 

dev Interpret character or block special devices on the filesystem. 

exec Permit execution of binaries. 

noauto Can only be mounted explicitly (that is, the -a option does not cause the filesystem to 
be mounted). 

nodev Do not interpret character or block special devices on the filesystem. This option is 
useful for a server that has filesystens containing special devices for architectures other 
than its own. 

noexec Do not allow execution of any binaries on the mounted filesystem. This option is useful 
for a server that has filesystems containing binaries for architectures other than its own. 

nosuid Do not allow set-user-identifier or set-group-identifier bits to take effect. 

nouser Forbid an ordinary (that is, non-root) user to mount the filesystem. 

remount Attempt to remount an already-mounted filesystem. T his is commonly used to change 
the mount flags for a filesysten, especially to make a read-only filesystem writable 

ro M ount the filesystem read-only. 

rw M ount the filesystem read-write. 

suid Allow set-user-identifier or s¢-group-identifier bits to take effect. 

sync All 1/0 to the filesystem should be done synchronously. 

user Allow an ordinary user to mount the filesystem. O rdinary users always have the 


following options activated: noexec, nosuid, and nodev (unless overridden by the super- 
user by using, for example, the following option line user, exec, dev, suid. 


The following options apply only to certain filesystems: 


case=val ue For the hpfs filesystem, specify case as lower Or asis. 

check=val ve T alls the ext2 filesystem kernel codeto do some more checks while the filesystem is 
mounted. Currently (0.99.15), the following values can be specified with this option: 

none No extra check is performed by thekernel code 

normal The inodes and blocks bitmaps are checked when the filesystem is mounted (thisis the 
default). 

strict In addition to the normal checks, block deallocation checks that the block to freeisin 
the data zone 


check=val ue For the msdos filesystem, three different levd's of specificity can be chosen: 
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relaxed 


normal 


strict 


conv=val ue 


binary 
text 
auto 


U ppercase and lowercase are accepted and equivalent, long name parts are truncated (for 
example, verlongname. foobar becoméS verylong. foo), leading and embedded spaces are 
accepted in each name part (name and extension). 

Like relaxed but many special characters (*, 2, <, spaces, and so on) are rgected. Thisis 
the default. 

Like norma, but names may not contain long parts and special characters that are 
sometimes used on Linux but are not accepted by M S-D OS are rejected (+, =, spaces, 
and so on). 

For the msdos, hpfs, and isog6ee filesystems, specify file conversion aS binary, text, Or 
auto. The isogeee filesystem also allows value to be mtext. 

Themsdos filesysten can perform crtr<->nL (MS-DOS text format to UNIX text 
format) conversion in the kernel. The following conversion modes are available: 

No translation is performed. T his isthe default. 

CRLF<->NL translation is performed on all files. 

CRLF<->NL translation is performed on all files that don’t havea wdl-known binary 
extension. T he list of known extensions can be found at the beginning of 
fs/msdos/misc.c (aS Of 09913r, thelist is exe, com, bin, app, sys, drv, ovl, ovr, obj, lib, 
dll, pif, arc, zip, lha, 1zh, zoo, tar, z, arj, tz, taz, tzp, tpz, gif, bmp, tif, gl, jpg, pcx, 
tfm, vf, gf, pk, pxl, and dvi). 


Programs that do computed 1seeks won't likein-kernd text conversion. 


For filesystems mounted in binary mode aconversion tool (fromdos/todos) is available. 


block=val ue 
bsdgroups 
cruft 


debug 


debug 


errors=val ue 


continue 
remount, ro 
panic 


fat=value 


gid=value 


B grpid 


map=val ue 


nocheck 
nogrpid 


For the isog66e filesystem, set the block size 

See grpid. 

For the isoge6e filesystem, set the cruft flag to y. T his option is available because there 
are buggy premastering programs out there that leave junk in the top byte of the file 
size. T his option clears the top byte but restricts files to 16M B maximum in the process. 


For the msdos filesystem, turn on the debug flag. A version string and alist of filesystem 
parameters is printed. (T hese data are also printed if the parameters appear to be 
inconsistent.) 

For the ext2fs filesystem, cause the kernel code to display thefilesystem parameters 
when the filesystem is mounted. 

For the ext2ts filesystem, specify the error behavior: 


No special action is taken on errors (except marking the filesystem as erroneous). Thisis 
the default. 

The filesystem is remounted read only, and subsequent writes are refused. 

When an error is detected, the system panics. 

For the msdos filesystem, specify either a 12-bit fat or a16-bit fat. This overrides the 
automatic FAT type detection routine Use with caution! 

For the msdos and hpfs filesystems, give every file a gia equal to value. 

Causes the ext2fs to use the BSD behavior when creating files: Files are created with the 
group ID of their parent directory. 


For the isoge6e filesystem, specify mapping as off Or normal. |n general, non-Rock 
Ridge discs haveall the filenames in uppercase, and all the filevames havea ;1 
appended. The map option strips the ;1 and makes the name lowercase. (See also 
norock.) 

For the ext2fs, turns off checking (See check=none). 

Causes the ext2fs to use the System V behavior when creating files. Files are created 
with the group ID of the creating process, unless the setgid bit is se on the parent 
directory. This is the default for all Linux filesystems. 


mount, unmount EI 


norock N ormal isog6ao filenames appear in a 8.3 format (that is, D O S-like restrictions on 
filename length), and in addition, all characters are in uppercase. Also there isno field 
for file ownership, protection, number of links, provision for block/character devices, 
and so on. 
Rock Ridge is an extension to isogeea that provides all of these U N IX-like features. 
Basically, there are extensions to each directory record that supply all of the additional 
information, and when Rock Ridge isin use, the filesystem is indistinguishable from a 
normal UN IX filesystem (except that it is read only, of course). 
The norock switch disables the use of Rock Ridge extensions, even if available. (See also 


map.) 

quiet For the msdos filesystem, turn on the quiet flag. Attempts to chown or chmod files do not 
yield errors, although they fail. U se with caution! 

sb=val ve For the ext2 filesystem, use an alternate superblock located at block value. value iS 


numbered in 1024-byte blocks. An ext2 filesystem usually has backups of the superblock 
at blocks 1, 8193, 16385, and so on. 


sysvgroups See nogrpid. 

uid=val ve For the msdos and hpfs filesystems, give every file a uid equal to value. 

umask=val ue For the msdos and hpfs filesystems, give every file a umask Of val ve. The radix defaults to 
octal. 


The full set of options applied is determined by first extracting the options for the filesystem from the fstab table, then 
applying any options specified by the -o argument, and finally applying the -r or -w option. 


If the msdos filesystem detects an inconsistency, it reports an error and sets the filesystem to read only. The filesystem can be 
made writable again by renounting it. 


-r The filesystem object isto be mounted read only. 

-t vistype The argument following the -t is used to indicate the filesystem type. T he filesystem 
types that are currently supported are listed in linux/fs/filesystems.c: minux, ext, ext2, 
xiafs, msdos, hpfs, proc, nfs, iso9660, sysv, xenix, coherent. N ote that that last three are 
equivalent and that xenix and coherent will be removed at some point in the future; use 
sysv instead. 

The type minix is the default. If no -t option is given, or if the auto type is specified, the 
superblock is probed for the filesystem type (minix, ext, ext2, and xia are supported). If 
this probe failsand /proc/filesystems exists, then all the filesystems listed are tried, 
except for those labeled nodev (such aS proc and nfs). 

N ote that the auto type may be useful for user-mounted floppies. For example, the mount 
command mounts all filesystems except those of type msdos and ext: 


mount -a -t nomsdos,ext 


“V Verbose mode. 
-W The filesystem object isto be read and write 
-n M ount without writing in /etc/mtab. 


umount removes the special device grafted at point node from the filesystem tree. 
O ptions for the umount command: 


-a All of the filesystems described in /etc/mtab are unmounted. 

-t vistype Is used to indicate the actions should only betaken on filesystems of the specified type. 
M orethan one type may be specified in a comma-separated list. T he list of filesystem 
types can be prefixed with no to specify the filesystem types on which no action should 
be taken. (See example for the mount command.) 
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FILES 
/etc/fstab Filesystem table 
/etc/mtab~ Lock file 
/etc/mtab.tmp Temporary file 
SEE ALSO 
mount(2), umount(2), fstab(5), swapon(8) 
BUGS 


It is possible for a corrupted filesystem to cause a crash. 


Some Linux filesystems don’t support -o synchronous (the ext2fs does support synchronous updates (ala BSD ) when 
mounted with the sync option). 


The -o remount may not be able to change mount parameters (all ext2ts parameters, except sb, are changeable with a 
remount, for example, but you can’t change gid or umask for the dosfs). 


HISTORY 
A mount command appeared in Version 6, AT&T UNIX. 


AUTHORS AND CONTRIBUTORS 
The Linux mount command has along and continuing history. T he following major releases are noted with the name of the 
primary modifier: 
0.97.3: Doug Quale (quale@saavik.cs.wisc.edu) 
0.98.5: H.J. Lu (hlu@eecs.wsu. edu) 
0.99.2: Rick Sladkey (jrs@world.std.com) 
0.99.6: Rick Sladkey (jrs@world.std.com) 
0.99.10: Stephen T weedie (sct@dcs.ed.ac.uk) 
0.99.14: Rick Sladkey (jrs@world.std.com) 
(Filesysten-specific information added to man page on 27 N ovember 1993 by Rik Faith with alot of information and text 
from the following filesystem authors: W erner Almesberger, Eric Youngdale, and Remy Card.) 
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mountd 
mountd— N FS mount daemon. 


SYNOPSIS 


/usr/etc/rpc.mountd [\-f\--exports-file\][\-dhnprv\] 
[\--debug\][\--exports-file=file\] [\--help\] 
[\--allow-non-root\][\--re-export\][\--version\] 


DESCRIPTION 
The mountd program is an N FS mount daemon. 
OPTIONS 
-f OF --exports-file This option specifies the exports file, listing the clients that this server is prepared to 


serve and parameters to apply to each such mount (see exports(5)). By default, exports 
are read from /etc/exports. 


named-xfer EI 


-d OF --debug Log each transaction verbosely to the syslog. 
-h Or --help Provide a short hap summary. 
-n Or --allow-non-root Allow incoming mount requests to be honored even if they do not originate from 


reserved IP ports. Someolder N FS client implementations require this. Some newer 
NFS client implementations don’t believe in reserved port checking. 


-p OF --promiscuous Put the server into promiscuous mode where it will serve any host on the network. 


-r Of --re-export Allow imported N FS filesystems to be exported. This can be used to turn a machine 
into an NFS multiplier. Caution should be used when reexporting loopback N FS 
mounts because reentering the mount point results in deadlock between the N FS client 
and the NFS serve. 


-v OF --version Report the current version number of the program. 
SEE ALSO 
exports(5), nfsd(8), ugidd(8C ) 


BUGS 


The current implementation (still) does not keep track of renote mounts. 
13 Octobe 1993 


named-xfer 


named -xfer— Ancillary agent for inbound zone transfers. 


SYNOPSIS 
named-xfer -z zone_to_transfer -f db file -s serial_no [ -d debuglevel ] 
[-l debug log file ][-t trace file ][-p port# ][-S ] nameserver 
DESCRIPTION 


named-xfer iSan ancillary program executed by named(8) to perform an inbound zone transfer. It is rary executed directly 
and only by system administrators who are trying to debug a zone transfer problen. See RFCs 1033, 1034, and 1035 for 
more information on the Internat name-domain system. 





Options are 

“2 Specifies the name of the zone to be transferred. 

-f Specifies the name of the file into which the zone should be dumped when it is received 
from the primary server. 

-s Specifies the serial number of the current copy of this zone If the SOA RR you get from 
the primary server does not havea serial number higher than this, the transfer is aborted. 

-d Print debugging information. A number after the a determines the level of messages 
printed. 

-1 Specifies a log file for debugging messages. T he default is system-dependent but is 
usually in /var/tmp or /usr/tmp. N ote that this only appliesif -d is also specified. 

-t Specifies a trace file that contains a protocol trace of the zone transfer. T his is probably 
only of interest to people debugging the nameserver itself. 

-p Usea different port numbe. T he default is the standard port number as returned by 
getservbyname(3) for service “domain”. 

-S Perform a restricted transfer of only the SOA, NS records, and glue A records for the 


zone. The SOA record is not loaded by named but is used to determine when to verify 
the NS records. See the stubs directive in namea(8) for more information. 
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Additional arguments are taken as nameserver addresses in so-called “dotted-quad” syntax only; no hostnames are allowed 
here At least one address must be specified. Any additional addresses are tried in order if the first one fails to transfer 
successfully. 


SEE ALSO 


named(8), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 
1035, RFC 1123, NameServer O perationsG uide for BIN D 


26 June1993 


named 


named— Internet domain nameserver. 


SYNOPSIS 


named [ -d debuglevel J[-p port#[/localport#]][{-b} bootfile ][-q ][-r ] 


DESCRIPTION 


named is the Internet domain nameserver. See RFCs 1033, 1034, and 1035 for more information on the Internat name 
domain system. Without any arguments, named reads the default boot file /etc/named.boot, reads any initial data, and listens 


for queries. 

Options are 

-d Print debugging information. A number after the a determines the level of messages 
printed. 

-p Use nonstandard port numbers. T he default is the standard port number as returned by 
getservbyname(3) for service “domain”. T he argument can specify two port numbers 
separated by a slash (/), in which case the first port isthat used when contacting remote 
servers and the second one isthe service port bound by the local instance of named. This 
is used mostly for debugging purposes. 

-b Use an alternate boot file This is optional and allows you to specify a file with a leading 
dash. 

-q Trace all incoming queries if named has been compiled with aryLoa defined. N ote that 
this option is deprecated in favor of the boot file directive options query-log. 

-r Turns recursion off in the server. Answers can come only from local (primary or 


secondary) zones. T his can be used on root servers. N ote that this option is deprecated 
in favor of the boot file directive options no-recursion. 


Any additional argument is taken as the name of the boot file If multiple boot files are specified, only the last is used. 


The boot file contains information about where the nameserver is to ge its initial data. Lines in the boot file cannot be 
continued on subsequent lines. The following is a small example: 


; boot file for name server 

directory /usr/local/adm/named 

; type domain source host/file backup file 

cache . root.cache 

primary Berkeley.EDU berkeley.edu.zone 

primary 32.128.IN-ADDR.ARPA ucbhosts.rev 

secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak 
secondary 6.32.128.IN-ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak 
primary 0.0.127.IN-ADDR.ARPA localhost.rev 


named [| 


forwarders 10.0.0.78 10.2.0.78 

limit transfers-in 10 

limit datasize 64M 

options forward-only query-log fake-iquery 


The directory line causes the server to change its working directory to the directory specified. This can beimportant for the 
correct processing of $1ncLupE files in primary zone files. 


The cache line specifies that data in root.cache isto be placed in the backup cache. 


Its main use is to specify data such as locations of root domain servers. T his cache is not used during normal operation, but is 
used as “hints” to find the current root servers. The file root. cache isin the same format aS berkeley.edu. zone. T here can be 
more than one cache file specified. The root.cache file should be retrieved periodically from FTP.RS. INTERNIC.NET because it 
contains a list of root servers, and this list changes periodically. 


The first sample primary line states that the file berkeley. edu. zone contains authoritative data for the Berkeley.EDU zone The 
file berkeley. edu. zone contains data in the master file format described in RFC 883. All domain namesare relative to the 
origin, in this case, Berkeley. EDU (See below for a more detailed description). The second primary line states that the file 
ucbhosts.rev contains authoritative data for the domain 32.128. 1N-ADDR.ARPA, which is used to translate addresses in network 
128.32 to hostnames. Each master file should begin with an SOA record for the zone (see below). 


The first sample secondary line specifies that all authoritative data under cc.Berkeley.Ebu is to be transferred from the 
nameserver at 128.32.137.8. If the transfer fails, it tries 128.32.137.3 and continues trying the addresses, up to ten, listed on 
this line. The secondary copy is also authoritative for the specified domain. T he first non-dotted-quad address on this line is 
taken asa filename in which to back up the transferred zone The nameserver loads the zone from this backup file if it exists 
when it boots, providing a complete copy even if the master servers are unreachable W henever a new copy of the domain is 
received by automatic zone transfer from one of the master servers, this file is updated. If no filename is given, a temporary 
fileis used and deleted after each successful zone transfer. T his is not recommended because it is a needless waste of 
bandwidth. The second sample secondary line states that the address-to-hostname mapping for the subnet 128.32.136 should 
be obtained from the same list of master servers as the previous zone. 


The forwarders line specifies the addresses of sitewide servers that will acceot recursive queries from other servers. If the boot 
file specifies one or more forwarders, then the server sends all queries for data not in the cache to the forwarders first. Each 
forwarder is asked in turn until an answer is returned or thelist is exhausted. If no answer is forthcoming from a forwarde,, 
the server continues as it would have without the forwarders line unlessit isin forward-only mode. The forwarding facility is 
useful to cause a large sitewide cache to be generated on a master and to reduce traffic over links to outside servers. It can also 
be used to allow servers to run that do not have direct access to the Internet but want to look up exterior names anyway. 


The slave line (deprecated) is alowed for backward compatibility. Its meaning is identical to options forward-only. 


The sortlist line can be used to indicate networks that are to be preferred over other networks. Queries for host addresses 
from hosts on the same network as the server receive responses with local network addresses listed first, then addresses on the 
sort list, and then other addresses. 





The xfrnets directive (not shown) can be used to implement primitive access control. If this directiveis given, your 
nameserver only answers zone transfer requests from hosts that are on networks listed in your xfrnets directives. This 
directive may also be given as tcplist for compatibility with older, interim servers. 


The include directive (not shown) can be used to process the contents of some other file as though they appeared in place of 
the include directive This is useful if you havea lot of zones or if you have logical groupings of zones that are maintained by 
different people. The include directive takes one argument, the name of the file whose contents are to be included. No 
quotes are necessary around the filename. 





The bogusns directive (not shown) tells BIN D that no queries are to besent to the specified nameserver addresses (which are 
specified as dotted quads, not as domain names). Thisis useful when you know that some popular server has bad datain a 
zone or cache, and you want to avoid contamination while the problen is being fixed. 


The 1imit directive can be used to changeBIN D ’sinternal limits, some of which (datasize, for example) are implemented 
by the system and others (such aS transfers-in) by BIN D itself. The number following the limit name can be scaled by 
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postfixing ak, m, or g for kilobytes, megabytes, and gigabytes respectively. datasize’s argument sets the process data size 
enforced by the kernd. N ote that not all systems provide a call to implement this; on such systems, the use of thedatasize 
parameter of limit resultsin a warning message. transfers -in’s argument is the number of named-xfer subprocesses that 
BIN D will spawn at any one time. transfers-per-ns’s argument is the maximum number of zone transfers to be simulta- 
neously initiated to any given remote nameserver. 


The options directive introduces a Boolean specifier that changes the behavior of BIN D. M orethan one option can be 
specified in a single directive. T he currently defined options are as follows: no-recursion, which causes BIN D to answer with 
a referral rather than actual data whenever it recaves a query for anameit is not authoritative for. Don’t set this on a server 
that is listed in any host’s resolv.cont file no-fetch-glue keeps BIND from fetching missing glue when constructing the 
“additional data” section of aresponse this can be used in conjunction with no-recursion to prevent BIN D's cache from ever 
growing in size or becoming corrupted. query -10g causes all queries to be logged via sysiog(3). This is alot of data; don’t 
turn it on lightly. forward-only Causes the server to query only its forwarders. This option is usually used on a machine that 
wants to run a server but for physical or administrative reasons cannot be given access to the Internet. fake-iquery tells 

BIN D to send back a useless and bogus reply to “inverse queries” rather than respond with an error. T hisis hapful if you 
have a lot of microcomputers or SunO S hosts or both. 


Themax-fetch directive (not shown) is allowed for backward compatibility; its meaning is identical to 1imit transfers-in. 
T he master file consists of control information and a list of resource records for objects in the zone of the forms: 


$INCLUDE <filename><opt_domain> 
$ORIGIN <domai n> 
<domain><opt_ttl> <opt_class><type><resource record data> 


domain iS. for root, e for the current origin, or a standard domain name. If domain isastandard domain name that does not 
end with ., the current origin is appended to the domain. Domain names ending with . are unmodified. The opt _domain 
fidd is used to define an origin for the datain an included file. It is equivalent to placing a sortain statement before the first 
line of the included file T he field is optional. N a@ther the opt_domain fidd nor sortain statenents in theincluded file modify 
the current origin for this file Theopt_tt! fidd isan optional integer number for the time to-live field. It defaults to a, 
meaning the minimum value specified in the SOA record for the zone Theopt_class field isthe object address type; 
currently only onetype is supported, | N, for objects connected to the DARPA Interna. The type field contains one of the 
following tokens; the data expected in theresource_record_data field isin parentheses: 


A A host address (dotted quad). 

NS An authoritative nameserver (domain). 

MIX A mail exchanger (domain), preceded by a preference value (0..32767) with lower 
numeric values representing higher logical preferences. 

CNAME The canonical name for an alias (domain). 

SOA M arks the start of a zone of authority (domain of originating host, domain address of 


maintainer, a serial number and the following parameters in seconds: refresh, retry, 
expire, aNd minimum TTL (SC@RFC 883)). 


NULL A null resource record (no format or data). 

RP A responsible person for some domain name (mailbox, TXT-referral). 
PTR A domain name pointer (domain). 

HINFO H ost information (cpu_type, 0S type). 


Resource records usually end at the end of aline but may be continued across lines between opging and closing parentheses. 
Comments are introduced by semicolons and continue to the end of theline 


N ote that there are other resource record types, not shown here You should consult the BIN D Operations GUID e(BOG) 
for the complete list. Some resource record types may have been standardized in newer RFCs but not yet implemented in 
this version of BIND. 


Each master zone file should begin with an SOA record for the zone. A sample SOA record follows: 


named 1337 


@ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. ( 


1989020501 ; serial 
10800 ; refresh 


3600 ; retry 
3600000 ; expire 
86400 ) ; minimum 


TheSOA specifies a serial number, which should be changed each time the master file is changed. N ote that the serial 
number can be given asa dotted number, but this is a very unwise thing to do because the translation to normal integers is 
via concatenation rather than multiplication and addition. You can spd out the year, month, day of month, and 0..99 
version number and still fit inside the unsigned 32-bit size of this fidd. It’s true that we will haveto rethink this strategy in 
the year 4294, but we're not worried about it. Secondary servers check the serial number at intervals specified by the refresh 
timein seconds; if the serial number changes, a zonetransfer is done to load the new data. I f a master server cannot be 
contacted when a refresh is due, the retry time specifies the interval at which refreshes should be attempted. If a master server 
cannot be contacted within the interval given by the expire time, all data from the zone is discarded by secondary servers. 
Theminimum value is the time-to-live (TT L) used by records in the file with no explicit time to-live value 


NOTES 


The boot file directives domain and suffixes have been obsoleted by a more useful resolver-based implementation of suffixing 
for partially qualified domain names. The prior mechanisms could fail under anumber of situations, especially when then 
local nameserver did not have complete information. 


The following signals have the specified effect when sent to the server process using the ki11(1) command: 


SIGHUP 


SIGINT 


SIGIOT 


SIGSYS 


SIGTERM 


SIGUSR1 


SIGUSR2 
SIGWINCH 


FILES 


/etc/named.boot 
/etc/named.pid 
/var/run/named.pid 
/var/tmp/named_dump.db 
/var/tmp/named.run 


/var/tmp/named.stats 


Causes server to read named. boot and rdoad the database. If the server is built with the 
FORCED RELOAD compile-time option, then sicHup also causes the server to check the serial 
number on all secondary zones. U sually, the serial numbers are only checked at the 

SO A-specified intervals. 


Dumps the current database and cache to /var/tmp/named_dump.db. 


Dumps statistics data into /var/tmp/named.stats if the server is compiled with -pstars. 
Statistics data is appended to the file Some systems use s1GaBrT rather than siaroT for 
this. 


Dumps the profiling data in /var/tmp if the server is compiled with profiling (the server 
forks, changes directories, and exits). 


Dumps the primary and secondary database files. U sed to save modified data on 
shutdown if the server is compiled with dynamic updating enabled. 


Turns on debugging; each steusr1 increments debug level (staemt on older systems 
without sreusr1). 


Turns off debugging completely (staFre on older systems without stcusr2). 


Toggles logging of all incoming queries via syslog(3) (requires server to have bean built 
with the aryLoe option). 


N ameserver configuration boot file 
The process 1D (on older systems) 
The process!D (on newer systems) 
Dump of the nameserver database 
D ebug output 

N ameserver statistics data 
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SEE ALSO 


kill(1), gethostbyname(3), signal(2), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 
1033, RFC 1034, RFC 1035, RFC 1123, NameServer O perationsGU ID efor BIND 


20 June1995 


named. reload 


named.reload— C ause the nameserver to synchronize its database. 


DESCRIPTION 


This command sends a sicHup to the running nameserver. T his signal is documented in namea(8). 


BUGS 


It does not check to see if the nameserver is actually running and could use a stale pid cache file, which may result in the 
death of an unrdated process. 


SEE ALSO 


named(8), named. restart(8) 


26 June1993 


named.restart 


named.restart— Stop and restart the nameserver. 


DESCRIPTION 


This command sends a stekILL to the running nameserver and then starts anew one 


BUGS 


It does not check to see if the nameserver is actually running and could use a stale pid cache file, which may result in the 
death of an unrdated process. 


It does not wait after killing the old server before starting a new one. Because the server could take some time to die and the 
new one experiences a fatal error if the old oneisn’t gone by the time it starts, you can be left in a situation where you have 
no nameserver at all. 


SEE ALSO 


named(8), named. reload(8) 
26 June1993 


ndc 


ndc— N ame daemon control interface. 


SYNOPSIS 


nde directive [ ... ] 


netstat 
DESCRIPTION 


This command allows the nameserver administrator to send various signals to the nameserver or to restart it. Zero or more 
directives may be given from the following list: 


status Displays the current status of named as shown by ps(1). 

dumpdb Causes named to dump its database and cache to /var/tmp/named_dump.db (uses the INT 
signal.) 

reload Causes named to check the serial numbers of all primary and secondary zones and to 
reload those that have changed (uses the Hur signal.) 

stats Causes named to dump its statistics to /var/tmp/named.stats (uses the roT or aBrT signal.) 

trace Causes named to increment its “tracing level” by one. W henever the tracing level is 


nonzero, trace information is written to /var/tmp/named.run. Higher tracing levels result 
in more detailed information (uses the usr1 signal). 


notrace Causes named to set its “tracing levd” to zero, closing /var/tmp/named.run if it isopen 
(uses the usr2 signal). 
querylog Causes named to toggle the “query logging” feature, which results in a syslog(3) of each 


incoming query (uses the wncH signal). N ote that query logging consumes quite a lot of 
log file space. T his directive may also be given as qrylog. 


start Causes named to be started as long as it isn’t already running. 
stop Causes named to be stopped if it is running. 
restart Causes named to bekilled and restarted. 

BUGS 


Arguments to named are not preserved by restart or Known by start. Some mechanism for controlling the parameters and 
environment should exist. 


Implemented as a sh(1) script. 


AUTHOR 


Paul Vixie (Internet Software C onsortium) 


SEE ALSO 


named(8), named.reload(8), named. restart(8) 
27 November 1994 


netstat 








netstat— Display active network connections 
SYNOPSIS 
netstat [[-a ; [-t | -u yj -w]] [-n ; -0] | -x] [-¢] 
netstat -r [-c] [-n] 
netstat -v 
DESCRIPTION 
netstat displays the status of network connections on either TCP, UDP, or RAW sockets to the system. By default, netstat 
only displays status on those T CP sockets that are not in the LtsTen state (that is, connections to active processes). To obtain 


information about the kernel routing table, netstat may be invoked with the option -r. A listing of internal UN IX 
connections can be obtained by invoking netstat with the option -x. 
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netstat’s display includes the following information for each socket: 


Proto 
Recv-Q 
Send-Q 
Local Address 


Foreign Address 


(State) 


ESTABLISHED 
SYN SENT 
SYN RECV 
FIN WAIT1 
FIN WAIT2 
TIME WAIT 
CLOSED 
CLOSE WAIT 
LAST ACK 
LISTEN 
UNKNOWN 


The protocol (either TCP or UD P) used by the socket. 
The count of bytes not copied by the user program connected to this socket. 
The count of bytes not acknowledged by the remote host. 


The local address (local hostname) and port number of the socket. U nless the -n switch 
is given, the socket address is resolved to its canonical hostname, and the port number is 
translated into the corresponding service name. 

The remote address (remote hostname) and port number of the socket. As with the local 
address:port, the -n switch turns off hostname and service name resolution. 


The state of the socket. Because there are no statesin RAW and usually no states used in 
UDP, this row may be left blank. U sually, this can be one of several values: 


The socket has an established connection. 

The socket is actively attempting to establish a connection. 

The connection is being initialized. 

The socket is closed, and the connection is shutting down. 

Connection is closed, and the socket is waiting for a shutdown from the remote end. 
The socket is waiting after close for renote shutdown retransmission. 

The socket is not bang used. 

Theremote end has shut down, waiting for the socket to close 

The remote end shut down, and the socket is closed. Waiting for acknowledgment. 
The socket is listening for incoming connections. 

The state of the socket is unknown. 





If netstat iSinvoked with the option -o, additional information is displayed after the state info. This information is shown 
like this: keyword (time/backoff) and an optional asterisk. The keyword shows the state of the timer bdonging to the socka, 
the time displayed (in seconds) is how long it will take the timer to expire, the backoff value indicates the current retry count 
for data transmission, and the asterisk indicates that this timer isin the expiration queue. Thelatter might be removed in 
future but is helpful for debugging the T C P-Code for now. 


Invoked with the option -x, netstat displays a list of all active UN IX internal communication sockets. 


netstat’s display includes the following information for each socket: 


Proto 
RefCnt 
Flags 


Type 

SOCK DGRAM 
SOCK STREAM 
SOCK RAW 

SOCK RDM 

SOCK SEQPACKET 
SOCK PACKET 


UNKNOWN 
State 
FREE 


The protocol (usually UN 1X) used by the socket. 
The reference count (attached processes via this socket). 


The only known flag to meisso accepton (displayed as acc); otherwise, left blank. 
SO ACCEPTON iS used on unconnected sockets if thar corresponding processes are waiting 
for a connect request. 


There are several types of socket access: 

The socket is used in D atagram (connectionless) mode. 

Thisis a stream (connection) socket. 

The socket is used as a raw socket. 

This one serves reliably delivered messages. 

This is a sequential packet socket. 

This socket type is used as a Linux-specific way to get packets at the dev (kerne)) levd. It 


is assumed to be used to write things such as RARP (Reverse Address Resolution 
Protocol) and similar things on the user level. 


W ho ever knows, what future will bring; just fill in here :-) 
This fidd will contain one of the following keywords: 
The socket is not allocated. 


netstat 


LISTENING The socket is listening for a connection request. 

UNCONNECTED The socket is not connected to anothe one 

CONNECTING The socket is about to establish a connection. 

CONNECTED The socket is connected. 

DISCONNECTING The socket is disconnecting. 

UNKNOWN This state should never happen. 

Path This displays the pathname that the corresponding processes attached to the socket. 


The network routing table (invoked with netstat -r) shows up the following information: 


Destination net/address The destination address of a resolved host or hand-entered network is displayed. U nless 
the option -n is given, the hosts or nets are resolved. An entry named default shows up 
the default route for the kernel. 








Gateway address If there is no asterisk (*) displayed, any data is routed to the dedicated gateway. 
Flags Possible routing flags are 
U This route is usable. 
G Destination is a gateway. 
H Destination isa host entry. 
N D estination isa N et entry. 
R Route will be reinstated after timeout. 
D This one is created dynamically (by redirection). 
M This oneis modified dynamically (by redirection). 
RefC nt Reference count for this route. 
Use H ow many times this route was used yet. 
| face This is the name of the interface where this route beongs. 
OPTIONS 
-a Display information about all Internet sockets, such asTCP, UDP, and RAW, 
including those sockets that are listening only. 
-C Generate a continuous listing of network status: network status is displayed every second 
until the program isinterrupted. 
-n Causes netstat not to resolve hostnames and service names when displaying renote and 
local address and port information. 
-0 Display timer states, expiration times, and backoff state. 
-r Display kernel routing table. 
-t Display information about TCP sockets only, including those that are listening. 
-U Display information about UD P sockets only. 
“V Print version information. 
-W Display information about raw sockets. 
“x Display information about UNIX domain sockets. 
FILES 
/proc/net/tcp TCP socket information 
/proc/net/udp UDP socket information 
/proc/net/raw RAW socket information 


/proc/net/unix UNIX domain socket information 
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/proc/net/route Kernd routing information 
/etc/services The services translation 
BUGS 
N one reported yet (5/20/93). 
AUTHORS 


The netstat user interface was written by Fred Baumgarten (dcéiq@insu1.etec.uni-karlsruhe.de). Theman page is basically 
by M att Welsh (mawetc. cornell. edu). 
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makeactive, makehistory, newsrequeue 


makeactive, makehistory, newsrequeue— | OOls to recover U senet databases 


SYNOPSIS 


makeactive [ -m ][-o ] 

makehistory [ -b ][-f filename ][-i ][-n ][-o ][-r ][-s size ] 

[-T tmpdir ][-u [ -v]] 

newsrequeue [ -a active J[-h history ][-d days ][-1 ][-n newsfeeds ][input ] 


DESCRIPTION 


makeactive invokes find(1) to get a list of all directories in the news spool tree, /news/spool. It discards directories named 
lost+found aS wall as those that havea period in them. It scans all other directories for all-numeric filenames and determines 
the highest and lowest number. The program’s output is a set of active(5) file lines. Because there is no way to know if a 
group is moderated or disabled, the fourth fidd of all entries is y. Also, mid-level directories that aren't newsgroups are also 
created as newsgroups with no entries. (For example, there is a comp.sources.unix group, but no comp.sources.) 


If the -o flag isused, makeactive reads an existing active file for the list of group names and just renumber all groups. It 
preserves the fourth field of the active file if one is present. T his is analogous to the ctlinnd(8) renumber command, except 
that innd(8) should be throttled or not running. Do not use this flag with output redirected to the standard active file! 


If the -m flag isgiven, then makeactive attempts to adjust thehighest and lowest article numbers wherever possible. If articles 
are found in anewsgroup, thenumbers reflect what was found. If no articles are found in a newsgroup, the high number 
from the old file is kept, and the low number is set to onemore than the high numbe. This flag may only be used if the -o 
flag is used. 


makeactive exits with nonzero status if any problems occur. A typical way to use the program is with the following /bin/sh 
commands: 


ctlinnd throttle "Rebuilding active file" 
TEMP=${TMPDIR - /tmp}/act$$ 
if [ -f /var/lib/news/active ] ; then 
if makeactive -o >${TEMP} ; then 
mv ${TEMP} /var/lib/news/active 
Fi 
else 
if makeactive >${TEMP} ; then 
# Edit to restore moderated 
# and aliased groups. 


mv ${TEMP} /var/lib/news/active 
fi 
fi 
ctlinnd reload active "New active file" 


makeactive, makehistory, navsrequeue 


makehistory reouilds the history(5) text file and the associated dbz(3) database. The default name of the text file is 
/news/1ib/history; to specify a different name, use the -+ flag. makehistory scans the active(5) file to determine which 
newsgroup directories within the spool directory, /news/spool, should be scanned. (If a group is removed, but its spool 
directory still exists, makehistory ignoresit.) The program reads each file found and writes a history linefor it. If the -b flag 
is used, then makehistory removes any articles that do not have valid M essage!D headersin them. 


After the text file is written, makehistory builds the dbz database. If the -f flag is used, then the database files are named 
file.dir and file.pag. If the -+ flag is not used, then a temporary link to thename history.n is made and the database files 
are written aS history.n.pag and history.n.dir. If the -o flag is used, then the link is not made and any existing history files 
are overwritten. If the old database exists, makehistory uses it to determine the size of the new database To ignore theold 
database, use the -i flag. Using the -o flag implies the -i flag. T he program also ignores any old database if the -s flag is used 
to specify the approximate number of entries in the new database. Accurately specifying the size is an optimization that 
creates a more efficient database. (T he size should be the estimated eventual size of the file typically the size of the old file) 
For more information, see the discussion of dbzfresh and dbzsize in dbz(3). 


If the -u flag isgiven, then makehistory assumes that innd is running. It pauses the server while scanning and then sends 
addhist Commands (see ctlinnd(8)) to the server for any article that is not found in the dbz database. The command 
makehistory -bu iSuseful after a systen crash to delete any mangled articles and bring the article database back into a more 
consistent state. If the -v flag isused with the -u flag, then makehistory puts a copy of all added lines on its standard output. 


To scan the spool directory without rebuilding the dbz files, use the -n flag. If used with -u, the server is not paused while 
scanning. T o just build the dbz files from an existing text file use the -r flag. T he -i or -s flags can be useful if there are no 
valid dbz files to use. A typical way to use this program is with the following /bin/sh commands: 


ctlinnd throttle "Rebuilding history file" 
cd /news/1lib 
if makehistory -n -f history.n ; then 


else 

echo Error creating history file! 

exit 1 

fi 

# The following line can be used to retain expired history. 
# It is not necessary for the history file to be sorted. 
# awk 'NF==2 { print; }' <history >>history.n 

# View history file for mistakes. 

if makehistory -r -s ‘we -l <history' -f history.n; then 
mv history.n history 

mv history.n.dir history.dir 

mv history.n.pag history.pag 

fi 

ctlinnd go " 


makehistory needs to create a temporary file that contains one line for each article it finds, which can become very large. T his 
fileis created in the /tmp directory. T he tupp1r environment variable may be used to specify a different directory. Alterna- 
tively, the -T flag may be used to specify a temporary directory. In addition, the sort(1) that is invoked during the build 
writes large temporary files (often to /var/tmp, but see your systan man pages). If the -7 flag is used, then the flag and its 
value are passed to sort. On most systems, this changes the temporary directory that sort uses. If used, this flag and its value 
are passed on to the sort(1) command that is invoked during the build. 


makehistory does not handle symbolic links. If the news spool area is split across multiple partitions, the following commands 
should probably be run before the database is regenerated: 


cd /news/spool 
find . -type 1 -name '[1-9]*' -print | xargs -t rm 


M ake sure to run the command on all the appropriate partitions! 
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newsrequeue Can be used to rewrite batchfiles after a system crash. It operates in two modes. In the first mode it first reads 
the active and newsfeeds (5) files to determine where the different newsgroups are to be distributed. T 0 specify alternate 
locations for these files, use the -a or -n flags. It then opens thehi story database. T 0 specify a different file use the -h flag. 


Oncethe files are opened, newsrequeue reads from the specified input file or standard input if no file is specified. Each line 
should havea single M essage-ID , surrounded in angle brackets; any other text on thelineis ignored. For example the 
history file (or atrailing subset of it) is acceptable input to the program operating in this mode. If the -a flag is used, then 
only articles that were received within the specified number of days are processed. 

newsrequeue uses the first two fields of the newsfeed entry— the siterame and the excludes field and the patterns and 
distribs fidd. It ignores all flagsin the third field except for then field and also ignores the fourth field altogether. 


The second mode is used if the -1 flag is used. In this mode, it reads from the specified i nput file or standard input if no file 
is specified. Each line should look like an innd log entry. It parses entries for accepted articles, looks up the M essage-ID in 
the history database to get the filename, and then scans the list of sites. 


In either mode the output of newsrequeue consists of one line for each article that should be forwarded. Each such line 
contains the M essage-ID , the filename, and the list of sites that should receive the article. The output is suitable for piping 
into filechan(8). 


HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


active(5), ctlinnd(8), dbz(3), filechan(8), history(5), innd(8), newsfeeds(5) 


news daily 

news .daily— Do regular U senet system administration 
SYNOPSIS 

news.daily [ keyword... ] 


innwatch [ -t sleeptime ][-f controlfile ][-1l logfile ] 
expirerm file 
inncheck [ -v ][-pedantic ][-perms [ -fix ]][-noperms ][file... ] 


DESCRIPTION 
news.daily performs anumber of important U sent administrative functions. This includes producing a status report, 
removing old news articles, processing log files, rotating the archived log files, renumbering the active file, removing any old 
socket files found in the firewall directory, and collecting the output. T his program should be run unde the news 
administrator's ID , not as root. 
By default, news. daily performs all its functions and mails the output to the news administrator, usenet. By specifying 
keywords on thecommand line, it is possibleto modify the functions performed, as wall as change the arguments given to 
expire(8) and expireover(8). 
news.daily should be run oncea day, typically out of cron(8). It may berun more often, but such invocations should at least 
use the norotate Keyword to prevent the log files from being processed and rotated too fast. 


The shlock(1) program is used to prevent simultaneous executions. 
The following keywords may be used: 


delayrm This uses the -z flag when invoking expire and expireover. T henames of articles to be 
removed are written to atemporary file and then removed after expiration by calling 
expirerm. 


news.daily 


nostat This keyword disables the status report generated by innstat (see news1og(8)). Without 
this keyword, the status report isthe first function performed, just prior to obtaining the 
news.daily lock. 


noexpire By default, expire isinvoked to remove old news articles. U sing this keyword disables 
this function. 
noexplog expire usually appends information to /var/1log/news/expire.log (S62 newslog(5)). Using 


this keyword causes the expire output to be handled as part of news. daily’s output. It 
has no effect if the noexpire keyword is used. 

flags='expire\args' By default, expire isinvoked with the an argument of -v1. Using this keyword changes 
the arguments to those specified. Be careful to use quotes if multiple arguments are 
needed. This keyword has no effect if the noexpire keyword is used. 


nologs After expiration, scanlogs(8) is invoked to process the log files. U sing this keyword 
disables all log processing functions. 
norotate By default, log processing includes rotating and cleaning out log files. Using this 


keyword disables the rotating and cleaning aspect of the log processing. T he log files are 
only scanned for information and no contents are altered. T his keyword has no effect if 
the nologs keyword is used. 


norenumber This keyword disables the ctlinnd(8) renumber operation. U sually, the low watermark 
for all newsgroups (see active(5)) is reset. 

norm By default, any socket ctlinnd socket that has not been modified for two days is 
removed. U sing this keyword disables this function. 

nomail news.daily usually sends a mail message containing the results to the administrator. 


Using this keyword causes this message to be sent to stdout and stderr instead. U sually, 
all utilities invoked by the script have their stdout and stderr redirected into afile. If the 
fileis enpty, no message is sent. 

expireover The expireover program is called after expiration to purge the overview databases. 

expireoverflags='expireovernargs' If the expireover keyword is used, this keyword may be used to specify the flags to be 
passed to expireover. If the delayrm keyword is used, then the default value is -z and the 
list of deleted files; otherwise, the default value is -s. 

/full/path The program specified by the given path is executed just before any expiration is done. 
A typical useis to specify an alternate expiration program and use the noexpire keyword. 
M ultiple programs may be specified; they are invoked in order. 


The norotate keyword is passed on to scanlogs if it isinvoked. expirerm is a script that removes a list of files. The specified 
file lists the files. It is sorted and then fed into a pipdine responsible for doing the removal, usually fastrm(8). | f there seemed 
to bea problem renoving the files, then mail is sent to the news administrator. | f there were no problems, then fileis 
renamed to /var/log/news/expire. list where it is kept (for safety) until the next day’s expiration. 





innwatch iS a script that can be started at news boot time. It periodically— every si eepti me seconds— examines the load 
average and the number of free blocks and inodes on the spool partition, as described by its control file, innwatch.ct1(5). If 
the load gets too high or the disk gets too full, it throttles the server. W hen the condition restores, it unblocks the server. In 
addition, on each pass through the loop, it checks the specified log file to see if it has been modified and sends mail to the 
news administrator if so. It is usually a good idea to set this to the sys1og(3) file that receives critical news messages. U pon 
receipt of an interrupt signal, innwatch reports its status in the file /news/1ib/innwatch. status. 


inncheck iS a per1(1) script that verifies the syntax and permissions of all InterN etN ews configuration files. If no files are 
specified, it checks all files. A filename may be followed by an equal sign and a path to indicate the pathname to use for the 
file For example, newsfeeds=/tmp/nt checks the syntax of anew newsfeeds(5) without requiring it to be installed. If the -v 
flag is used, it prints status information as it checks each file If the -pedantic flag is used, it checks the files for omissions that 
are not strictly errors but might indicate a configuration error. 








If any file is specified, only the permissions on those files are checked. T he -noperms flag suppresses this check. If the -perms 
flag is used, the script verifies the ownership and permissions of all files. T he -fix flag can also be used so that the output can 
be executed as a shell script. 


Part VIII: Administration and Privileged Commands 


HISTORY 


news.daily and this manual page were written by Landon Curt Noll (chongo@toad.com) and Rich $alz (rsalz@uunet.uu.net). 
inncheck was written by Brendan K ehoe (brendanécs.widener.edu) and Rich. 
innwatch was written by M ike C ooper (mcooper@usc.edu) and (kre@munnari.oz.au). 


SEE ALSO 


active(5), ctlinnd(8), expire(8), fastrm(8), newslog(5), newslog(8), innwatch.ct1(5), shlock(1) 


newslog 


newslog— M aintenance of U send log files 


SYNOPSIS 


scanlogs [ norotate ][nonn ] 
writelog name text... 
innstat 

tally.unwanted 
tally.control 

innlog. awk 


DESCRIPTION 


scanlogs Summarizes the information recorded in the 1nn log files (See news1og(5)). By default, it also rotates and cleans out 
the logs. It is usually invoked by the news.daily(8) script. 


The following keywords are accepted: 


norotate Using this keyword disables the rotating and cleaning aspect of the log processing: 
The logs files are only scanned for information and no contents are altered. 

nonn Usually, the nn log fileis scanned and rotated. U sing this keyword disables this 
function. 


If scanlogs isinvoked more than oncea day, the norotate keyword should be used to prevent premature log cleaning. 


The writelog script isused to write a log entry or send it as mail. Thename parameter specifies the name of the log file where 
the entry should be written. If it isthe word mai1, then theentry is mailed to the news administrator, U senet. T he data that 
iswritten or sent consists of the text given on thecommand line, followed by standard input indented by four spaces. 
shlock(1) is used to avoid simultaneous updates to a single log file 


The innstat script prints a snapshot of the 1nn system. It displays the operating mode of the server, as well as disk usage and 
the status of all log and lock files. 


The rest of the scripts described here are usually invoked by scanlogs. T hey parse log files that are described in news1og(5) 
and the server's article log file described in inna(8). 


tally.unwanted script parses the article log file to update the cumulative list of articles posted to unwanted newsgroups, 
unwanted. log. 


tally.control reads its standard input, which should be the newgroup.1og and rmgroup. log log files. It updates the cumulative 
list of newsgroup creations and deletions, control. 1og. 


innlog.awk iS an awk(1) script that summarizes the activity that inna and nnrpd(8) report to syslog. 


HISTORY 


Written by Landon Curt N oll (chongo@toad.com) and Rich $alz (rsalze@uunet.uu.net) for |nterN etN ews. 
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SEE ALSO 


innd(8) newslog(5), news.daily(8), nnrpa(8) 


nfsd 


nfsd— NFS service daemon. 


SYNOPSIS 


/usr/etc/rpc.nfsd [\-f\exports-file\ ][\-dhnprv\] 
[\--debug\][\--exports-file=file\] [\--help\] 
[\--allow-non-root\][\--re-export\][\--version\] 


DESCRIPTION 


The nfsd program isan N FS service daanon that handles client filesystem requests. U nlike nfsd on some other systems, nfsd 
operates as a normal user-level process. The server also differs from other NFS server implementations in that it mounts an 
entire file hierarchy not limited by the boundaries of physical filesystems. The implementation allows the clients read-only or 
read-write access to the file hierarchy of the server machine. 


The mountd program starts an ancillary user-levad mount daenon. 


OPTIONS 

-f Or --exports-file This option specifies the exports file, listing the clients that this server is prepared to 
serve and parameters to apply to each such mount (see exports(5)). By default, exports 
are read from /etc/exports. 

-d OF --debug Log each transaction verbosely to the syslog. 

-h Or --help Provide a short hap summary. 

-n Or --allow-non-root Allow incoming NFS requests to be honored even if they do not originate from reserved 
IP ports. Some older N FS client implementations require this. Some newer N FS client 
implementations don’t believe in reserved port checking. 

-p OF --promiscuous Put theserver into promiscuous mode where it serves any host on the network. 

-r OF --re-export Allow imported N FS filesystems to be exported. T his can be used to turn a machine 
into an NFS multiplier. Caution should be used when re-exporting loopback N FS 
mounts because re-entering the mount point results in deadlock between the NFS client 
and the NFS serve. 

-v OF --version Report the current version number of the program. 

SEE ALSO 
exports(5), mountd(8), ugidd(8C ) 
AUTHORS 


M ark Shand wrote the original unfsd. Don Becker extended unfsd to support authentication and allow read-write access and 
called it hnfs. Rick Sladkey added host matching, showmount -e Support, mountd authentication, inetd support, and all the 
portability and configuration code. 


13 October 1993 


nnrpd 


nnrpd— N NTP server for on-campus hosts. 
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SYNOPSIS 


nnrpd [ -r reason ][-s title padding ][-S host ][-t ] 


DESCRIPTION 


nnrpd isan NNTP server for newsreaders. It acceots commands on its standard input and responds on its standard output. 
It isusually invoked by inna(8) with those descriptors attached to a remote client connection. 


If the -r flag is used, then nnrpd rejects the incoming connection giving reason as the text. T his flag is used by innd when it is 
paused or throttled. 


Unlike innd, nnrpd supports all NN TP commands for user-oriented reading and posting. 


nnrpd uses the nnrp.access(5) file to control who is authorized to access the U senet database. It also rejects connections if the 
load average is greater than 16. 


Aseach command is received, nnrpd tries to change its argv array so that ps(1) prints the command being executed. T 0 get a 
full display, the -s flag may be used with along string as its argument, which is overwritten when the program changes its 
title 


On exit, nnrpd reports usage statistics through syslog(3). 





If the -t flag is used, all client commands and initial responses are traced by reporting them in syslog. T his flag is set by inna 
under the control of the ctlinna(8) trace command and is toggled upon receipt of asicHuP; See signal(2). 


If the -s flag is used, all postings are forwarded to the specified host, which should bethe master N NTP server. T his flag is 
set by inna if it is started with the -s flag. 


nnrpd can accept multimedia postings that follow the MIME standard as long as such postings are also acceptable as SM T P 
messages. See the discussion of the M1M E headersin inn.conf(5). 


PROTOCOL DIFFERENCES 
nnrpd implements the N NTP commands defined in RFC 977 with the following differences: 


m The ihave command isnot implemented. Users should be using the post command to post articles. 

@ Thesilave command isnot implemented. This command has never been fully defined. 

@ Thelist command may be followed by the optional word active.times, distributions, distrib.pats, newsgroups, OF 
overview. fmt to get alist of when newsgroups where created, a list of valid distributions, a file specifying default 
distribution patterns, aone-per-line description of the current set of newsgroups, or a listing of the overview. fmt(5) file 
Thecommand list active is equivalent to thelist command. This is acommon extension. 

@ Thexhdr, authinfo user, and authinfo pass commands are implemented. T hese are based on the reference U NIX 
implementation; no other documentation is available 

m Anevcommand, xpat header range'MessageID pat [morepat...], is provided. The first argument is the case-insensitive 
name of the header to be searched. The second argument is either an article range or a single M essage-D as specified in 
RFC 977. Thethird argument is a wildmat(3)-style pattern; if there are additional arguments, they are joined together 
separated by a single space to form the complete pattern. This command is similar to the xhdr command. It returns a 221 
response code, followed by the text response of all article numbers that match the pattern. 

Mm Thelistgroup group command is provided. This isa comment extension. It is equivalent to the group command, except 
that the reply is a multi-line response containing the list of all article numbers in the group. 

m Thexgtitle [group] command is provided. This extension is used by AN U-N ews, It returns a 282 reply code, followed 
by aone line description of all newsgroups that match the pattern. T he default is the current group. 

M Thexover [range] command is provided. It returns a 224 reply code, followed by the overview data for the specified 
range; the default is to return the data for the current article. 

m Thexpath MessageID Command is provided; see innd(8). 

m Thedate command is provided; this is based on the draft NNTP protocol revision. It returns a one line response code 
of 111 followed by the GMT date and time on the server in the form yy YY mmDDhh mms s . 


nntpsend 
HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN €&tN ews. O verview support added by Rob Robertston 
(rob@violet.berkeley.edu) and Rich in January 1993. 


SEE ALSO 


ctlinnd(8), innd(8), inn.conf(5), nnrp.access(5), signal(2), wildmat(3) 


nntpsend 


nntpsend— Send U set articles to remote site. 


SYNOPSIS 


nntpsend [ -d ][-p ][-r ][-S ][-s size ][-t timeout ] 
[-T timelimit ][sitename fqdn ] ... 


DESCRIPTION 


nntpsend iS a front end that invokes innxmit(1) to send U sené articles to aremote NNTP site 


The sites to be fed may be specified by givingsitename fqdn pairson the command line If no such pairs are given, nntpsend 
defaults to the information given in the nntpsend.ct1(5) config file 


Thesitename should be thename of the site as specified in the newsfeeds(5) file Thefqdn should be the hostname 
or IP address of the ranote site. An innxmit is launched for sites with queued news. All innxmit processes are 
spawned in the background and the script waits for them all to finish before returning. O utput is sent to the file 
/var/log/news /nntpsend.1og. T 0 avoid overwhelming the local system, nntpsend waits five seconds before spawning 
each child. The flag -a is always given asa flag to innxmit. 


nntpsend expects that the batchfile for a site is named /news/spool/out.going/sitename. 1 0 prevent batchfile corruption, 
shlock(1) is used to “lock” these files. 


The -p, -r, -S, -t, and -T flags are passed on to the child innxmit program. N ote that if the -p flag is used then no connection 
ismadeand no articles are fed to the remote site. It is useful to have cron(8) invoke nntpsend with this flag in case a site 
cannot be reached for an extended period of time 


If the -s flag is used, then shrinkfile(1) isinvoked to peform a tail truncation on the batchfile and the flag is passed to it. 


When sitename fqdn pairs are given on the command line, any flags given on the command completdy describe how innxmit 
and shrinkfile operate. When no such pairs are given on the command line then the information found in nntpsend.ct1 
becomes the default flags for that site Any flags given on the command line override the default flags for the site. 


For example, with the following control file 


nsavax:erehwon.nsavax.gov::-S -t60 
group70:group70.org:: 
walldrug:walldrug.com:1m: -T1800 -t300 


Thecommand 


nntpsend 


will result in the following: 


Sitename Truncation Innxmit flags 
nsavax (none) -a -S -t60 
group70 (none) -a -t180 
walldrug 1m -a -T1800 -t300 
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The command 
nntpsend -d -11200 


will result in the following: 


Sitename Truncation Innxmit flags 


nsavax (none) -a -d -S -T1200 -t60 
group70 (none) -a -d -71200 -t180 
walldrug 1m -a -d -T1200 -t300 
Thecommand 


nntpsend -s 5m -T1200 nsavax erehwon.nsavax.gov group7® group70.org 


will result in the following: 


Sitename Truncation Innxmit flags 
nsavax 5m -a -T1200 -t180 
group70 5m -a -71200 -t180 


Remember that -a is always given, and -+ defaults to 180. 


HISTORY 


Written by Landon Curt N oll (chongo@toad.com) and Rich $alz (rsalzeuunet.uu.net) for |nterN etN ews. 


SEE ALSO 


innxmit(1), newsfeeds(5), nntpsend.ct1(5), shrinkfile(1) 


nslookup 


nslookup— Query Internet nameservers interactively. 


SYNOPSIS 


nslookup [ -option ... ] [ host-to-find | -[server ]] 


DESCRIPTION 


nslookup iSa program to query Internet domain nameservers. nslookup has two modes: interactive and non-interactive. 
Interactive mode allows the user to query nameservers for information about various hosts and domains or to print alist of 
hosts in a domain. N on-interactive mode is used to print just the name and requested information for a host or domain. 


ARGUMENTS 


Interactive mode is entered in the following cases: 


m When no arguments are given (the default nameserver is used) 
m Whe thefirst argument isa hyphen (-) and the second argument is the hostname or Interne address of a nameserver 


N on-interactive mode is used when the name or Internet address of the host to be looked up is given as the first argument. 
The optional second argument specifies the host name or address of a nameserver. 


The options listed under the set command can be specified in the .nslookuprc file in the user's home directory if they are 
listed one per line. O ptions can also be specified on the command line if they precede the arguments and are prefixed with a 
hyphen. For example, to change the default query type to host information, and the initial timeout to 10 seconds, type 


nslookup -query=hinfo -timeout=10 


nsdookup EI 
INTERACTIVE COMMANDS 


Commands may be interrupted at any time by typing Ctrl+C. To exit, type Ctrl+D (EOF) or type exit. The command-line 
length must be less than 256 characters. To treat a built-in command as ahostname, precede it with an escape character (n). 
N ote that an unrecognized command is interpreted as a hostname. 


host [server] Look up information for host using the current default server or using server if 
specified. If host isan Internet address and the query typeisa or ptr, thename of the 
host is returned. If host isanameand does not havea trailing period, the default 
domain name is appended to the name. (T his behavior depends on the state of the 
set options domain, srchlist, defname, and search). T 0 look up ahost not in the current 
domain, append a period to thename. 

server domain, lserver domain Change the default server to domain. server uses the initial server to look up informa- 
tion about domain, whereas server uses the current default server. If an authoritative 
answer can’t be found, the names of servers that might have the answer are returned. 

root Changes the default server to the server for the root of the domain name space. 
Currently, the host ns.internic.net isused. (This command is a synonym for 1server 
ns. internic.net.) T hename of the root server can be changed with theset root 


command. 
finger [name] [> filename], Connects with the finger server on the current host. T he current host is defined when 
finger [name ][>> filename] a previous lookup for a host was successful and returned address information (see the 


set query-type= A Command). name is optional. > and >> can be used to redirect output 
in the usual manner. 


1s [option] domain [> filename], List theinformation available for domain, optionally creating or appending to 


1s [option] domain [>> filename] filename. T he default output contains hostnames and their Internet addresses. opti on 

can be one of the following: 

-t querytype Lists all records of the specified type (see 
querytype). 

-a Lists aliases of hosts in the domain. Synonym for 
-t CNAME. 

-d Lists all records for the domain. Synonym for 

ANY. 
-h Lists CPU and operating system information for 


the domain. Synonym for -t HINFo. 

ists well-known services of hosts in the domain. 
Synonym for -t wks. When output is directed to a 
file, hash marks are printed for every 50 records 
received from the server. 

orts and lists the output of previous 1s commands 
with more(1). 


1 
wn 
rc 


wn 


view filename 





help, ? Prints a brief summary of commands. 

exit Exits the program. 

set keyword [=value] This command is used to change state information 
that affects the lookups. Valid keywords are 

all Prints the current values of the frequently used 


options to set. Information about the current 
default server and host is also printed. 


class=val ve Change the query class to one of the following: 
IN The! nternet class. 
CHAOS The Chaos class. 
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[no]debug 


[no]d2 


domain=name 


srchlist=namel/name2/... 


[no]defname 


[no]search 


port=val ue 


querytype=val ue, type=val ue 


[no]recurse 


retry=number 


HESIOD TheMIT AthenaH esiod class. 

ANY Wildcard (any of the above). 

The class specifies the protocol group of the information. (D efault =1n, abbreviation = 
cl.) 

Turn debugging mode on. A lot more information is printed about the packet sent to 
the server and the resulting answer. (D efault =nodebug, abbreviation =[nojdeb.) 

Turn exhaustive debugging mode on. Essentially, all fields of every packet are printed. 
(D efault =nod2.) 

Change the default domain name to name. T he default domain name is appended to a 
lookup request depending on the state of the defname and search options. T he domain 
search list contains the parents of the default domain if it has at least two components in 
its name. For example, if the default domain iscc.Berkeley.Ebu, the search list is 
CC.Berkeley.EDU and Berkeley.EDU. Use the set srchlist command to specify a different 
list. Use the set all command to display the list. (D efault = value from hostname, 
/etc/resolv.conf, OF LOCALDO-MAIN, abbreviation =do.) 

Change the default domain name to name1 and the domain search list to name1, name2, 
and so on. A maximum of six names separated by slashes (/) can be specified. For 
example, set srchlist=1cs.MIT.EDU/ai.MIT.EDU/MIT.EDU sets the domain to 1cs.MIT.EDU 
and the search list to the three names. T his command overrides the default domain 
name and search list of the set domain command. Use the set all command to display 
thelist. (D efault = value based on hostname, /etc/resolv.conf, OF LOCAL-DOMAIN, 
abbreviation =srchl.) 

If set, append the default domain name to a single component lookup request (that is, 
onethat does not contain a period). (D efault =defname, abbreviation =[nojdef.) 

If the lookup request contains at least one period but doesn’t end with a trailing period, 
append the domain names in the domain search list to the request until an answer is 
recaived. (D efault = search, abbreviation =[no]sea.) 

Change the default TCP/UDP nameserver port to val ve. (D efault =53, abbreviation = 
po.) 

Change the type of information query to one of the following: 


A The host's Internet address. 

CNAME The canonical name for an alias. 

HINFO Thehost CPU and operating system type. 

MINFO The mailbox or mail list information. 

MIX The mail exchanger. 

NS The nameserver for the named zone 

PTR The host name if the query is an Internet address; otherwise, the pointer 
to other information. 

SOA The domain's “start-of-authority” information. 

TXT The text information. 

UINFO Theuser information. 

WKS The supported well-known services. 


O ther types (ANY, AXFR, MB, MD, MF, NULL) are described in the RFC-1035 document. 

(D efault =a, abbreviations =q, ty.) 

Tell the nameserver to query other servers if it does not have the information. (D efault = 
recurse, abbreviation =[no]rec.) 

Se the number of retries to number. When a reply to a request is not received within a 
certain amount of time (changed with set timeout), the timeout period is doubled and 
the request is resent. T he retry value controls how many times a request is resent before 
giving up. (D efault =4, abbreviation =ret.) 


overchan [| 


root=host Change the name of the root server to host. T his affects the root command. (D efault = 
ns.internic.net, abbreviation =ro.) 

timeout=number Change the initial timeout interval for waiting for a reply to number seconds. Each retry 
doubles the timeout period. (D efault =5 seconds, abbreviation =ti.) 

[no]ve Always use a virtual circuit when sending requests to the serve. (D efault =nove, 
abbreviation =[no]v.) 

[no]ignoretc Ignore packet truncation errors, (D efault =noignoretc, abbreviation = [no] ig.) 

DIAGNOSTICS 

If the lookup request was not successful, an error message is printed. Possible errors are 

Timed out Theserve did not respond to a request after a certain amount of time (changed with 
set timeout=val ue) and acettain number of retries (changed with set retry=value). 

No response from server N 0 nameserver is running on the server machine. 

No records The server does not have resource records of the current query type for the host, 
although the hostname is valid. The query type is specified with the set querytype 
command. 

Non-existent domain The host or domain name does not exist. 

Connection refused, Theconnection to the name or finger server could not be made at the current time 

Network is unreachable This eror commonly occurs with 1s and finger requests. 

Server failure The nameserver found an internal inconsistency in its database and could not return a 
valid answer. 

Refused The nameserver refused to service the request. 

Format error The nameserver found that the request packet was not in the proper format. It may 
indicate an error in nslookup. 

FILES 

/Etc/Resolv.Contf Initial domain name and nameserver addresses. 

$HOME/.nslookupre User's initial options. 

/usr/share/misc/nslookup. help Summary of commands. 

ENVIRONMENT 
HOSTALIASES File containing host aliases. 
LOCALDOMAIN Overrides default domain. 
SEE ALSO 


resolver(3), resolver(5), named(8), RFC 1034 “Domain N ames - Concepts and Facilities,” RFC 1035 “Domain Names - 
Implementation and Specification” 


AUTHOR 


Andrew Cherenson 
24 June1990 


overchan 


overchan— U pdate the news overview database. 
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SYNOPSIS 


overchan [ -D dir ][-c ][file... ] 


DESCRIPTION 


overchan reads article data from files or standard input if none are specified. (A single dash in the file list means to read 
standard input.) It uses this information to update the news overview database overchan is designed to be used by 

InterN etN ews or the C N ews mkov packages to update the database as the articles come in. T he database for each newsgroup 
is stored in a filenamed . overview in anewsgroup directory within the overview database tree. 


overchan locks the database file (by locking an auxiliary file) before appending the new data. To purge data after articles have 
been expired, see expireover(8). 


By default, overchan processes its input as an INN Overview stream written as a wo entry in the newsfeeds(5) file 


overview: *:Tc ,WO:/news/bin/overchan 


This data consists of a line of text separated into two parts by a tab. The first part isa list of all relative pathnames where the 
article has been written with a single space between entries. The second part is the data to be written into the overview file, 
except that the initial article number is omitted. 


To process the output of the mkov(8) program, use the -c flag. This format is described in the nov distribution. 
The -p flag can be used to specify where the databases are stored. The default directory is /news/spool. 


HISTORY 


Written by Rob Robertson (rob@violet.berkeley.edu) and Rich $alz (rsalze@uunet.uu.net) for |InterN etN ews. 


SEE ALSO 


newsfeeds(5), newsoverview(5), newsoverview(8) 


pac— Printer/plotter accounting information. 
SYNOPSIS 

pac [-P printer] [-c] [-m] [-p price] [-s] [-r] [name ...] 
DESCRIPTION 


pac reads the printer/ plotter accounting files, accumulating the number of pages (the usual case) or feet (for raster devices) of 
paper consumed by each user and printing how much each user consumed in pages or feet and dollars. 


O ptions and operands available 


-P printer Accounting is done for the named printer. Usually, accounting is done for the default 
printer (site dependent), or the value of the environment variable printer is used. 

-C Flag causes the output to be sorted by cost; usually, the output is sorted alphabetically 
by name. 

-m Flag causes the hostnameto be ignored in the accounting file. T his allows for a user on 
multiple machines to have all his printing charges grouped together. 

-p price The value price is used for the cost in dollars instead of the default value of 0.02 or the 
price specified in /etc/printcap. 

-r Reverse the sorting order. 

-s Accounting information is summarized on the summary accounting file; this summari- 


zation is necessary because on a busy system, the accounting file can grow by several 
lines per day. 


pcnfsd [| 


names Statistics are only printed for users named; usually, statistics are printed for every user 
who has used any paper. 


FILES 


/var/account/?acct Raw accounting files 
/var/account/?_sum Summary accounting files 
/etc/printcap Printer capability database 


SEE ALSO 


printcap(5) 


BUGS 


Therelationship between the computed price and reality is as yet unknown. 


HISTORY 
The pac command appeared in BSD 4.0. 


BSD 4.2, 16 March 1991 


penfsd 


penfsd— (PC)NFS authentication and print request server 


SYNOPSIS 


/usr/etc/rpc.pcenfsd 


AVAILABILITY 
This program is fredy redistributable. 


DESCRIPTION 
penfsd isan RPC server that supports ONC clients on PC (DOS, 0S/2, M acintosh, and other) systems. T his page describes 
version 2 of the penfsd server. 
rpc.penfsd may be started from /etc/rc.local or by the ineta(8) superdaemon. It reads the configuration file 
/etc/penfsd.conf if present and then services RPC requests directed to program number 150001. T his release of the penfsd 
daemon supports both version 1 and version 2 of the penfsd protocol. Consult the rpcgen source file penfsd.x for details of 
the protocols. 
The requests serviced by penfsd fall into three categories: authentication, printing, and other. Only the authentication and 
printing services have administrative significance 


AUTHENTICATION 


W hen penfsd receives a PCNFSD AUTH OF PCNFSD2 AUTH request, it “logs in” the user by validating the username and password 
and returning the corresponding UID, GIDs, homedirectory, and umask. If penfsd was built with thewrmp compile time 
option, it also appends a record to the wtmp(5) database. If you do not want to record PC loginsin this way, you should add a 
line of the form 


wtmp off 


to the /etc/penfsd.cont file 


By default, penfsd only allows authentication or print requests for users with UID sin the range 101 to seee02. (This 
corresponds in svr4 to the range for non-systen accounts.) T o override this, you may add aline of the form 
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uidrange range[,range]... 


to the /etc/penfsd.conf file Here, each range isof the form uid or uid -uid, indicating an inclusive range 


PRINTING 


penfsd Supports a printing model based on the use of N FS to transfer the actual print data from the client to the server. The 
client system issues a PCNFSD_PR_INIT OF PCN-FSD2_PR_INIT request, and the server returns the path to aspool directory that the 
client may use and which is exported by NFS. penfsd creates a subdirectory for each of its clients: The parent directory is 
usually /usr/spool/penfs and the subdirectory is the hostname of the client system. If you want to use a different parent 
directory, you should add a line of the form 





spooldir path 
to the /etc/penfsd.cont file 


Onceaclient has mounted the spool directory using NFS and has transferred print data to afilein this directory, it issues a 
PCNFSD_PR_START OF PCNFSD2_PR_START request. penfsd handles this, and most other print-related requests, by constructing a 
command based on the printing services of the server operating system and executing the command using the identity of the 
PC user. Because this involves set-user-ID privileges, penfsd must be run as root. 


Every print request from the client includes the name of the printer that is to be used. In Linux, this name corresponds to a 
printer definition in the /etc/printcap(5) database. If you want to define a non-standard way of processing print data, you 
should define a new printer and arrange for the client to print to this printer. T here are two ways of setting up a new printer. 
The first involves the addition of an entry to /etc/printcap(5) and the creation of filters to perform the required processing. 
This is outside the scope of this discussion. In addition, penfsa includes a mechanism by which you can define virtual 
printers Known only to penfsd clients. Each printer is defined by a linein the /etc/penfsd.conf file of the following form: 


printer name alias-for command 


name isthename of the printer you want to define alias-for isthe name of a “real” printer that corresponds to this printer. 
For example, a request to display the queue for name is translated into the corresponding request for the printer ali as- for. If 
you have defined a printer in such a way that thereis no “real” printer to which it corresponds, use a single - for this fidd. 
(See the definition of the printer test for an example.) command isa command that will be executed whenever a fileis printed 
On name. T his command is executed by the shell at /bin/sh using the -c option. For complex operations, you should 
construct an executable shall program and invoke that in command. 


Consider the following sample /etc/penfsd.cont file: 
printer rotated lw /usr/local/bin/enscript -2r $FILE 
printer test - /usr/bin/cp $FILE/usr/tmp/$HOST$USER 


If a client systen prints a job on the printer rotated, the utility enscript isinvoked to pre-process the file $F1Le. In this case, 
the -2r option causes the file to be printed in two-column rotated format on the default PostScript printer. If the client 
requests a list of the print queue for the printer rotated, the penfsa daemon translates this into a request for a listing for the 
printer 1w. 


The printer test is used only for testing. Any file sent to this printer is copied into /usr/tmp. Any request to list the queue, 
check the status, and so on of printer test is rejected because theal ias-for is specified as -. 


plipconfig 
RECONFIGURATION 


penfsd detects when printers are added or deleted and rebuilds its list of valid printers. T 0 do this, it checks the modification 
time of /etc/printcap. H oweve,, it does not monitor the file /etc/penfsd.cont for updates; if you change this file, it is still 
necessary to kill and restart penfsa so the changes can take effect. 


FILE 
/etc/pcnfsd.conf 


SEE ALSO 
Ipr(1), 1prm(1), 1pc(8), 1pq(1) 
25 June1995 


plipconfig 


plipconfig— Fine-tune PLIP device parameters. 


SYNOPSIS 


plipconfig interface 
plipconfig interface [nibble NN] [trigger NN] [unit NN] 


DESCRIPTION 


plipconfig isused to improve PLIP performance by changing the default timing parameters used by the PLIP protocol. 
Results are dependent on the paralld port hardware, cable, and the CPU speed of each machineon each end of the PLIP 
link. 


If the singlei nterface argument is given, plipconfig displays the status of the given interface only. O therwise, it tries to set 
the options. 





OPTIONS 
nibble NN Sets the nibble wait valuein microseconds. D efault is 3000. 
trigger NN Sets the trigger wait value in microseconds. D efault is 500. 
unit NN Sets the number of units of delay. D efault is 1. 


In some cases, PLIP speed can be improved by lowering the default values. Values that are too low might cause excess use of 
CPU, poor interrupt response time resulting in serial ports dropping characters, or in dropping PLIP packets. Changing the 
plip MTU can also affect PLIP speed. 


SEE ALSO 


ifconfig(8) 


BUGS 


N one so far. 


AUTHOR 


John Paul M orrison (jmorriso@bogomips.ee.ubc.ca, ve7jpm@ve7 jpm.ampr.org) 
1 July 1994 
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ping 


ping— Send IC M P EcHo_REquesT packets to network hosts. 


SYNOPSIS 


/etc/ping [ -r ][-v ] host [ packetsize ][count ] 


DESCRIPTION 

TheDARPA Internet is a large and complex aggregation of network hardware, connected together by gateways. T racking a 

single-point hardware or software failure can often be difficult. Ping utilizes the |CM P protocol’s mandatory EcHo_REQUEST 

datagram to elicit an |C M P EcHo_REsPonsE from a host or gateway. EcHO_REQUEST datagrams (“pings”) havean IP and|ICMP 

header, followed by a struct timeval and then an arbitrary number of “pad” bytes used to fill out the packet. D efault 

datagram length is 64 bytes, but this may be changed using the command-lineoption. O ther options are 

-r Bypass the normal routing tables and send directly to a host on an attached network. If 
the host is not on adirectly attached network, an error is returned. This option can be 
used to ping alocal host through an interface that has no route through it (for example 
after the interface was dropped by routed(8C)). 


“V Verbose output. 1C M P packets other than EcHo_ResPonse that are received are listed. 
When using ping for fault isolation, it should first be run on the local host to verify that the local network interface is up and 
running. Then, hosts and gateways further away should be pinged. Ping sends one datagram per second and prints oneline 
of output for every EcHo_REsPonse returned. No output is produced if there is no response. If an optional count is given, only 
that number of requests is sent. Round-trip times and packet-loss statistics are computed. W hen all responses have been 
received or the program times out (with acount specified), or if the program is terminated with a stent, a brief summary is 
displayed. 


This program is intended for use in network testing, measurement, and management. It should be used primarily for manual 
fault isolation. Because of the load it could impose on the network, it is unwise to use ping during normal operations or from 
automated scripts. 


AUTHOR 


Mike M uuss 
SEE ALSO 
netstat(1), ifconfig(8) 
19 Septenber 1988 


portmap 

portmap— DARPA port to RPC program number mappe. 
SYNOPSIS 

portmap [-d] 


DESCRIPTION 


portmap iS a server that converts RPC program numbers into DARPA protocol port numbers. It must be running in order to 
make RPC calls. 


When an RPC serve isstarted, it tells portmap what port number it is listening to and what RPC program numbers it is 
prepared to serve When aclient wants to make an RPC call to a given program numbe,, it first contacts portmap on the 
server machine to determine the port number where RPC packets should be sent. 


powerd 


Usually, portmap forks and dissociates itself from the terminal like any other daemon. Portmap then logs errors using 
syslog(3). 


portmap Must be started before any RPC servers areinvoked. 


O ption available 


-d (debug) prevents portmap from running as a daemon and causes errors and debugging information to be printed to the 
standard error output. 


SEE ALSO 


inetd.conf(5), rpcinfo(8), ineta(8) 


BUGS 


If portmap crashes, all servers must be restarted. 


HISTORY 
The portmap command appeared in BSD 4.3. 
BSD 4.3, 16 March 1991 


powerd 

powerd— M onitor a serial line connected to a UPS. 
SYNOPSIS 

/etc/powerd serial-device 
DESCRIPTION 


powerd is adaemon process that sits in the background and monitors the state of theD CD line of the serial device. It is 
meant that this line is connected to aU PS (Uninterruptible Power Supply) so that it knows about the state of the UPS. As 
SOON aS powerd senses that the power is failing (it sees that DCD goes low) it notifies init(8) and init executes the powerwait 
and powerfail entries. | f powerd senses that the power has been restored, it notifies init again and init executes the 
powerokwait entries. 


ARGUMENTS 


serial-device Some serial port that is not being used by some other device and does not 
share an interrupt with any other serial port. 


DIAGNOSTICS 


powerd regularly checks the D SR line to see if it’s high. DSR should be directly connected to DTR and powerd Keeps that line 
high, so if DSR islow, something is wrong with the connection. powerd notifies you about this fact every two minutes. When 
it sees that the connection is restored, it will say so. 


IMPLEMENTATION 
It's pretty smple to connect your UPS to the Linux machine. T he steps are easy: 


1. Makesure you havean UPS with asimplerdais output: it should close its connections (make) if the power is gone, and 
it should open its connections (break) if the power is good. 

2. Buy aseial plug. Connect the DTR lineto the DSR line directly. Connect the DTR line and theDCD line with a10 
kilo ohm resistor. Connect the relais-output of the UPS to GROUND andtheDCD line If you don’t know what pins 
DSR, DTR, DCD and GROUND are you can always ask at the store where you bought the plug. 

3. You'reall set. 
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BUGS 


W all, it’s not a real bug but powerd should be able to do a broadcast or something on the Ethernet in case more Linux-boxes 
are connected to the same UPS and only one of them is connected to the UPS status line. 


SEE ALSO 


shutdown(8), init(8), inittab(5) 


AUTHOR 


Miquel van Smoorenburg (miquels@drinkel.n1.mugnet.org) 
14 February 1994 


pppd 


pppd— Point-to-Point Protocol daenon. 


SYNOPSIS 


pppd [ tty_name ][speed ][options ] 


DESCRIPTION 


The Point-to-Point Protocol (PPP) provides a method for transmitting datagrams over serial point-to-point links. PPP is 
composed of three parts: a method for encapsulating datagrams over serial links, an extensible Link Control Protocol (LCP), 
and a family of N work Control Protocols (N CP) for establishing and configuring different network-layer protocols. 


The encapsulation scheme is provided by driver code in the kernel. pppd provides the basic LCP, authentication support, and 
an NCP for establishing and configuring the Interne Protocol (IP) (called the!P Control Protocol, IPCP). 


FREQUENTLY USED OPTIONS 


tty_name Communicate over the named device. The string /dev/ is prepended if necessary. If no 
device name is given, or if the name of the controlling terminal is given, pppd uses the 
controlling terminal and does not fork to put itsdf in the background. 

speed Se the baud rate to speed (adecimal number). On systems such as 4.4BSD and 
NetBSD, any speed can be specified. O ther systems (such as SunO S) allow only a 
limited set of speeds. 

asyncmap map Se the async character map to map. This map describes which control characters cannot 
be successfully received over the serial line. pppd asks the peer to send these characters as 
a 2-byte escape sequence. The argument is a 32-bit hex number with each bit represent- 
ing acharacter to escape Bit 0 (00000001) represents the character oxee; bit 31 (80000000) 
represents the character ox1¢ or *. If multiple asyncmap options are given, the values are 
ored together. If no asyncmap option is given, no async character map is negotiated for 
the receive direction; the peer should then escape all control characters. 

auth Require the peer to authenticate itself before allowing network packets to be sent or 
received. 

connect p Use the executable or shal command specified by p to set up the serial line This script 
typically uses the chat(8) program to dia the modem and start the renote PPP session. 

ertscts Use hardware flow control (that is, RTS/CTS) to control the flow of data on the sevial 
port. If neither the crtscts nor the -crtscts option is given, the hardware flow control 
setting for the serial port is left unchanged. 

defaultroute Add a default route to the system routing tables, using the peer as the gateway, when 
IPCP negotiation is successfully completed. T his entry is removed when the PPP 
connection is broken. 





disconnect p Run the executable or shall command specified by p after pppd has terminated the link. 
This script could, for example, issue commands to the modem to cause it to hang up if 
hardware modem control signals were not available. 

escape XX ,V¥,..- Specifies that certain characters should be escaped on transmission (regardless of whether 
the peer requests them to be escaped with its async control characte: map). The 
characters to be escaped are specified as a list of hex numbers separated by commas. 
N ote that almost any character can be specified for the escape option, unlike the 
asyncmap Option, which only allows control characters to be specified. The characters 
that cannot be escaped are those with hex values 0x20 - ox3 Or oxse. 


file f Read options from filer (the format is described later). 

lock Specifies that pppa should create a U UC P-style lock file for the serial device to ensure 
exclusive access to the device. 

mrun Set theM RU (M aximum Receive U nit) value to n for negotiation. pppa asks the peer to 


send packets of no more than n bytes. The minimum MRU value is 128. The default 
MRU value is 1500. A value of 296 is recommended for slow links (40 bytes for TCP/IP 
header plus 256 bytes of data). 

mtu n Set theM TU (M aximum Transmit U nit) value to n. Unless the peer requests a smaller 
value viaM RU negotiation, pppa requests that the kernel networking code send data 
packets of no more than n bytes through the PPP network interface 

netmask n Se the interface netmask to n, a 32-bit netmask in decimal dot notation (such as 
255.255.255.0). If this option is given, the value specified is ored with the default 
netmask. T he default netmask is chosen based on the negotiated remote IP address; it is 
the appropriate network mask for the class of the remote! P address ored with the 
netmasks for any non- point-to-point network interfaces in the system that are on the 
same network. 

passive Enables the passive option in the LCP. With this option, pppa attempts to initiate a 
connection; if no reply is receded from the peer, pppa then waits passively for a valid 
LCP packet from the peer (instead of exiting as it does without this option). 


silent With this option, pppd does not transmit LCP packets to initiate a connection until a 
valid LCP packet is received from the peer (as for the passive option with ancient 
versions Of pppd). 

OPTIONS 
local |P address:remote IP address Se thelocal and/or remoteinterface|P addresses, Either one may be 


omitted. TheIP addresses can be specified with a host name or in decimal 
dot notation (such as 150.234.56.78). T he default local address is the 
(first) IP address of the system (unless the noipdefault option is given). 
The remote address is obtained from the peer if not specified in any 
option. Thus, in simple cases, this option isnot required. If alocal and/or 
remote IP address is specified with this option, pppd does not accept a 
different value from the peer in the IPC P negotiation, unless the 
ipcp-accept-local and/or ipcp-accept-remote options are given. 


-ac Disable Address/C ontrol compression negotiation (use default, address/ 
control field compression disabled). 

-all Don’t request or allow negotiation of any options for LCP and IPCP (use 
default values). 

-am Disable asyncmap negotiation (use the default asyncmap; that is, escape all 


control characters). 
-as n Same aS asyncmap n. 
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bsdcomp nr ,nt 


-bsdcomp 


+chap 


-chap 
chap-interval n 


chap-max-challenge n 


chap-restart n 


-ertscts 


debug 


-defaultroute 


-detach 


dns-addr n 


domain d 


-ip 


+ip-protocol 


-ip-protocol 


+ipx-protocol 


Request that the peer compress packets that it sends, using the 

BSD -Compress schene, with amaximum code size of nr bits and agree to 
compress packets sent to the peer with amaximum code size of nt bits. If 
at iSnot specified, it defaults to the value given for nr. Values in the range 
9 to 15 may be used for nr and nt; larger values give better compression 
but consume more kernel memory for compression dictionaries. 
Alternatively, a value of 0 for nr or nt disables compression in the 
corresponding direction. 

Disables compression; pppd does not request or agree to compress packets 
using the BSD -Compress scheme. 

Require the peer to authenticate itsdf using CH AP (Cryptographic 

H andshake Authentication Protocol) authentication. 

Don’t agree to authenticate using CH AP. 

If this option is given, pppa rechallenges the peer every n seconds. 

Sé& the maximum number of CH AP challenge transmissions to u (default 
iS 10). 

Set the CH AP restart interval (retransmission timeout for challenges) to n 
seconds (default is 3). 

Disable hardware flow control (RT S/CT S) on the sevial port. | f neither 
the crtscts nor the -crtscts option is given, the hardware flow control 
setting for the serial port is left unchanged. 

Increase debugging level (same as the debug option). 

Increase debugging level (same as -d). If this option is given, pppa logs the 
contents of all control packets sent or received in areadable form. The 
packets are logged through sysiog with facility daemon and leva debug. 
This information can be directed to a file by setting up /etc/syslog.contf 
appropriate y (see syslog. cont(5)). 

Disable the defaultroute option. The system administrator who wants to 
prevent users from creating default routes with pppd can do so by placing 
this option in the /etc/ppp/options file 

Don't fork to becomea background process (otherwise, pppd will do so if 
a serial device other than its controlling terminal is specified). 

This option sets the IP address or addresses for the D omain N ame Sever. 
It is used by Microsoft Windows clients. The primary DN S address is 
specified by the first instance of the dns-addr option. The secondary is 
specified by the second instance. 

Append the domain named to the local hostname for authentication 
purposes. For example if gethost-name() returnsthename porsche, but 
the fully qualified domain nameis porsche.quotron.com, you use the 
domain option to set the domain nameto aquotron.com. 

Disable IP address negotiation. If thisoption is used, the remote | P 
address must be specified with an option on the command line or in an 
options file 

Enablethe|PCP and IP protocols. Thisis the default condition. T his 
option is only needed if the default setting is -ip-protocol. 

Disable the|PCP and IP protocols. This should only be used if you know 
you are using a client that only understands |IPX and you don’t want to 
confuse the client with the PCP protocol. 

Enablethe|PXCP and |PX protocols. T hisis the default condition if 
your kernel supports IPX. This option is only needed if the default setting 
iS -ipx-protocol. If your kernel does not support IPX, this option has no 
effect. 


-ipx-protocol Disable the IPXCP and IPX protocols. This should only be used if you 
know you are using a client that only understands IP and you don’t want 
to confuse the client with the |PXCP protocol. 


ipcp-accept- local With this option, pppa accepts the peer’s idea of alocal IP address, even if 
the local IP address was specified in an option. 

ipcp-accept-remote With this option, pppa accepts the peers idea of its (remote) IP address, 
even if the remote !P address was specified in an option. 

ipcp-max-configure n Set the maximum number of IPCP configure request transmissions to n 
(default is 10). 

ipcp-max-failure n Set the maximum number of IPCP configure-N AK sreturned before 
starting to send configure-R gects instead to n (default is 10). 

ipcp-max-terminate n Set the maximum number of IPC P terminate request transmissions to n 
(default is 3). 

ipcp-restart n Set the PCP restart interval (retransmission timeout) to n seconds 
(default is 3). 

ipparam string Provides an extra parameter to theip-up and ip-down scripts. If this 
option is given, thestring supplied is given asthe sixth parameter to 
those scripts. 

ipx-network n Sé& the PX network number in the |PXCP configure request frame to n. 


There isno valid default. If this option is not specified, the network 
number is obtained from the pee. If the peer does not have the network 
number, the PX protocol is not started. This is a hexadecimal number 
and is entered without any leading sequence such as ex. It is related to the 
ipxcp-accept -network option. 

ipx-node n:m Se the|PX node numbers. The two node numbers are separated from 
each other with a colon character. The first number n is thelocal node 
number. T he second number m isthe peer’s node number. Each node 
number is a hexadecimal number to the maximum of ten significant 
digits. The nodenumbe’s on the ipx-network must be unique. Thee is 
no valid default. If this option is not specified, the node number is 
obtained from the peer. This option isa related to the ipxcp-accept- local 
and ipxcp-accept-remote options. 


ipx-router-name string Set the name of the router. T his isa string and is sent to the peer as 
information data. 
ipx-routing n Se the routing protocol to be recaved by this option. M ore than one 


instance of ipx-routing may be specified. The none option (0) may be 
specified as the only instance of ipx-routing. T he values are o for none, 2 
for RIP/SAP, and 4 for NLSP. 

ipxcp-accept - local Accept the peer’s N AK for the nodenumber specified in the ipx-node 
option. If anodenumber was specified and it is nonzero, the default isto 
insist that the value be used. If you include this option, you permit the 
peer to override the entry of the node numbe. 

ipxcp- accept - network Accept the peer’s N AK for the network number specified in the ipx- 
network option. If a network number was specified and it is nonzero, the 
default isto insist that the value be used. If you include this option, you 
permit the peer to override theentry of the node number. 

ipxcp-accept -remote Use the peer’s network number specified in the configure request frame. 
If anode number was specified for the peer and this option was not 
specified, the peer is forced to use the value that you specified. 

ipxcp-max-configure n Set the maximum number of IPXCP configure request frames that the 
system sends to n. The default is 10. 
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ipxcp-max-failure n Set the maximum number of IPXCP NAK frames that the local system 
sends before it rgects the options. T he default value is 3. 

ipxcp-max-terminate n Set the maximum number of IPXCP terminate request frames before the 
local system considers that the pee is not listening to them. T he default 
value is 3. 

kdebug n Enable debugging codein the kernel-level PPP driver. The argument n is 


a number that is the sum of the following values: 1 to enable general 
debug messages, 2 to request that the contents of recaved packets be 
printed, and 4 to request that the contents of transmitted packets be 
printed. 

lcp-echo-failure n If this option is given, pppd presumes the peer is dead ifn LCP echo- 
requests are sent without reca ving a valid LCP echo-reply. If this 
happens, pppd terminates the connection. U se of thisoption requires a 
nonzero value for the 1cp-echo-interval parameter. This option can be 
used to enable ppp to terminate after the physical connection has ben 
broken (for example, the moden has hung up) in situations where no 
hardware modem control lines are available 

lcp-echo-interval n If this option is given, pppa sends an LCP echo-request frame to the peer 
every n seconds. Under Linux, the echo-request is sent when no packets 
are received from the peer forn seconds. Usually, the peer should respond 
to the echo-request by sending an echo-reply. This option can be used 
with the 1cp-echo-failure option to detect that the peer is no longer 





connected. 

cp-max-configure n Set the maximum number of LCP configure-request transmissions to n 
(default is 10). 

cp-max-failure n Set the maximum number of LCP configureN AKs returned before 
starting to send configure-R gects instead to n (default is 10). 

cp-max-terminate n Set the maximum number of LCP terminate-request transmissions to n 
(default is 3). 

cp-restart n Se& the LCP restart interval (retransmission timeout) to n seconds (default 
iS 3), 

ocal Don’t use the moden control lines. W ith this option, pppd ignores the 
state of the CD (Carrier D etect) signal from the moden and does not 
change the state of the DT R (Data T eminal Ready) signal. 

ogin Use the systen password database for authenticating the peer using PAP, 
and record the user in the systan wtmp file. 

modem Use the modem control lines. T his option is the default. With this 


option, pppa waits for the CD (Carrier D etect) signal from the moden to 
be asserted when opening the serial device (unless a connect script is 
specified), and it drops the DTR (Data T erminal Ready) signal briefly 
when theconnection is taminated and before executing the connect 
script. On Ultrix, this option implies hardware flow control, as for the 
ertscts option. 





-mn Disable magic number negotiation. With this option, pppa cannot detect 
a looped-back line 

-mru Disable M RU (M aximumRecave Unit) negotiation. With this option, 
pppd uses the default M RU value of 1500 bytes. 

name n Sé& the name of the local system for authentication purposes to n. 

noipdefault Disables the default behavior when no local IP address is specified, which 
is to determine (if possible) the local IP address from the hostname. W ith 
this option, the peer must supply the local IP address during IPC P 


“Pp 

*pap 
“pap 
papcrypt 


pap-max-authreq n 


pap-restart n 


pap-timeout n 


-pe 


persist 


predicomp 


-predicomp 


proxyarp 


-proxyarp 


remotename n 


+ua p 


usehostname 


user U 


“Vj 


-vjccomp 


vj-max-slots n 


negotiation (unless it specified explicitly on the command line or in an 
options file). 

Same as the passive option. 

Require the peer to authenticate itself using PAP. 

Don’t agree to authenticate using PAP. 

Indicates that all secrets in the /etc/ppp/pap-secrets file, which are used 
for checking the identity of the peer, are encrypted, and thus pppd should 
not accept a password (before encryption) that is identical to the secret 
from the /etc/ppp/pap-secrets file. 

Sé& the maximum number of PAP authenticate request transmissions to n 
(default is 10). 

Sé& the PAP restart interval (retransmission timeout) to n seconds (default 
iS3). 

Set the maximum time that pppd waits for the peer to authenticate itself 
with PAP to n seconds (a means no limit). 

Disable protocol field compression negotiation (use default, protocol field 
compression disabled). 

Do not exit after a connection is terminated; instead, try to reopen the 
connection. 

Attempt to request that the peer send the local system frames, which have 
been compressed by the Predictor-1 compression. T he compression 
protocols must be loaded or this option isignored. 

Do not accept Predictor-1 compression, even if the peer wants to send 
this type of compression and support has been defined in the kernd. 

Add an entry to this system’s ARP (Address Resolution Protocol) table 
with theIP address of the peer and the Ethernet address of this system. 
Disable the proxyarp option. The systen administrator who wants to 
prevent users from creating proxy ARP entries with pppd can do so by 
placing this option in the /etc/ppp/options file 

Se the assumed name of the remote system for authentication purposes 
ton. 

Agree to authenticate using PAP (Password Authentication Protocol) if 
requested by the peer and use the data in filep for the user and password 
to send to the peer. The file contains the remote username, followed by a 
newline followed by the renote password, followed by anewline This 
option is obsolescent. 

Enforce the use of the hostname as the name of the local systen for 
authentication purposes (overrides the name option). 

Se& the username to use for authenticating this machine with the peer 
using PAP tou. 

Disable negotiation of Van J acobson-style TC P/IP header compression 
(use default, no compression). 

Disable the connection-ID compression option in Van J acobson style 
TCP/IP header compression. With this option, pppd does not omit the 
connection-ID byte from Van J acobson compressed T C P/IP headers or 
ask the peer to do so. 

Sets the number of connection slots to be used by the Van J acobson 
TCP/IP header compression and decompression code to n, which must be 
between 2 and 16 (inclusive). 


Part VIII: Administration and Privileged Commands 


xonxoff Use software flow control (XON/XO FF) to control the flow of data on 
the serial port. This option is only implemented on Linux systems at 
present. 
OPTIONS FILES 


Options can be taken from files as well asthe command line. pppa reads options from the files /etc/ppp/options and ~/.ppprc 
before looking at the command line. An options file is parsed into a series of words, delimited by whitespace. W hitespace can 
be included in aword by enclosing the word in quotes ("). A backslash (\) quotes the following character. A hash (#) starts a 
comment, which continues until the end of the line. 


AUTHENTICATION 


pppd provides systen administrators with sufficient access control so that PPP access to a server machine can be provided to 
legitimate users without fear of compromising the security of the server or thenetwork it’son. In part, thisis provided by the 
/etc/ppp/options file, where the administrator can place options to require authentication whenever pppd isrun, and in part 
by the PAP and CHAP secrets files, where the administrator can restrict the set of IP addresses that individual users can use. 


The default behavior of pppa is to agree to authenticate if requested and to not require authentication from the peer. 
H owever, pppd does not agree to authenticate itsaf with a particular protocol if it has no secrets that can be used to do so. 


Authentication is based on secrets, which are selected from secrets files (/etc/ppp/pap-secrets for PAP, 
/etc/ppp/chap-secrets for CHAP). Both secrets files have the same format, and both can store secrets for several combina- 
tions of server (authenticating peer) and client (peer being authenticated). N ote that pppa can be both a server and client and 
that different protocols can be used in the two directions if desired. 


A secrets file is parsed into words as for an options file A secret is specified by aline containing at least three words, in the 
order client name, server name, and secret. Any following words on the same line are taken to bea list of acceptable IP 
addresses for that client. If there are only three words on the line, it is assumed that any IP address is okay; to disallow all IP 
addresses, use -. If the secret starts with an e, what follows is assumed to be the name of afile from which to read the secret. 
A « asthe client or server name matches any name. W hen selecting a secret, pppd takes the best match— that is, the match 
with the fewest wildcards. 


A secrets file contains both secrets for use in authenticating other hosts and secrets that you use for authenticating yourself to 
others. W hich secret to use is chosen based on the names of the host (the local name) and its peer (the renotename). The 
local name is set as follows: 


If the usehostname option is given, Thelocal name is the hostname of this machine (with thedomain 
appended, if given). 

If the name option is given Use the argument of the first name option seen. 

If the local 1P address is specified with a Use that name Otherwise, use the hostname of this machine (with the 

hostname domain appended, if given). 


W hen authenticating yourself using PAP, there is also a username, which is the local name by default, but can be set with the 
user option or the +ua option. 


Theremote name is set as follows: 


If the renotename option is given Use the argument of the last remote-name option seen. 
If the renote IP address is specified with a Use that host name. O therwise the renote name is the null 
hostname tring "". 


Secrets are selected from the PAP secrets file as follows: 


m@ For authenticating the pee, look for a secret with client =username specified in the PAP authenticate request and 
serve =local name. 
m@ For authenticating yourself to the peer, look for a secret with client = your username and server = remote name. 


When authenticating the peer with PAP, asecret of "" matches any password supplied by the peer. If the password doesn’t 
match the secret, the password is encrypted using crypt( ) and checked against the secret again; thus secrets for authenticat- 
ing the peer can be stored in encrypted form. If the papcrypt option is given, the first (unencrypted) comparison is omitted 
for better security. 


If the login option was specified, the username and password are also checked against the system password database. T hus, 
the system administrator can set up the pap-secrets file to allow PPP access only to certain users and to restrict the set of IP 
addresses that each user can use. Typically, when using the login option, the secret in /etc/ppp/pap-secrets iS "" to avoid the 
need to have the same secret in two places. 


Secrets are selected from the CH AP secrets file as follows: 


m@ For authenticating the pee, look for a secret with client name specified in the CH AP-Response message and server 
=local name 

m For authenticating yourself to the peer, look for a secret with client =local name and serve —=name specified in the 
CHAP-C hallenge message. 


Authentication must be satisfactorily completed before|PCP (or any other N etwork Control Protocol) can be started. If 
authentication fails, pppd terminates the link (by closing LCP). If IPC P negotiates an unacceptable IP address for the remote 
host, IPCP is closed. IP packets can only be sent or received when IPCP is open. 





In some cases, it is desirable to allow some hosts that can’t authenticate themselves to connect and use one of a restricted set 
of IP addresses, even when the local host generally requires authentication. If the peer refuses to authenticate itself when 
requested, pppd takes that as equivalent to authenticating with PAP using the empty string for the username and password. 
Thus, by adding aline to the pap-secrets file, which specifies the empty string for the client and password, it is possible to 
allow restricted access to hosts that refuse to authenticate themselves. 


ROUTING 
When IPCP negotiation is completed successfully, pppd informs the kernel of the local and renote IP addresses for the PPP 
interface. T hisis sufficient to create a host route to the remote end of the link, which enables the peers to exchange | P 
packets. Communication with other machines generally requires further modification to routing tables and/or ARP (Address 
Resolution Protocol) tables. In some cases, thisis done automatically through the actions of the routed or gated daenons, 
but in most cases, some further intervention is required. 
Sometimes it is desirable to add a default route through the remote host, as in the case of a machine whose only connection 
to the Internet is through the PPP interface The defaultroute option Causes pppd to create such a default route when IPCP 
comes up and delete it when the link is terminated. 
In some cases, it is desirable to use proxy ARP— for example, on a server machine connected to aLAN — to allow other hosts 
to communicate with the remote host. The proxyarp option causes pppd to look for a network interface on the same subnet as 
the remote host (an interface supporting broadcast and ARP, which is up and not a point-to-point or loopback interface). If 
found, pppd creates a permanent, published ARP entry with the! P address of the remote host and the hardware address of 
the network interface found. 


EXAMPLES 
In the simplest case, you can connect the serial ports of two machines and issue a command like 
pppd /dev/ttya 9600 passive 


to each machine assuming there is no getty running on the sevial ports. If one machine has a getty running, you can use 
kermit Or tip on the other machine to log in to thefirst machine and issue a command like 


pppd passive 
Then exit from the communications program (making sure the connection isn’t dropped) and issue a command like 
pppd /dev/ttya 9600 
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The process of logging in to the other machineand starting pppd can be automated by using the connect option to run chat: 


pppd /dev/ttya 38400 connect ‘chat "" "" "login:" "username" 
"Password:" "pass-word" "% " "exec pppd passive"' 


(N ote however, that running chat like this leaves the password visible in the parameter list of pppd and chat.) 


If your serial connection is any more complicated than a piece of wire, you might need to arrange for some control characters 
to be escaped. In particular, it is often useful to escape XON (%Q) and XOFF (7S), using asyncmap agood. If the path 
includes a telnet, you probably should escape *] as well (asyncmap 200a0000). If the path includes an rlogin, you need to use 
the escape ff option on the end that is running the rlogin client because many rlogin implementations are not transparent; 
they remove the sequence (Oxff, Oxff, 0x73, 0x73, followed by any 8 bytes) from the stream. 


DIAGNOSTICS 


M essages are sent to the syslog daamon using the facility Loa_DAEMon. (T his can be overridden by recompiling pppd with the 
macro Loc_ppP defined as the desired facility.) To see the error and debug messages, you need to edit your /etc/syslog.cont 
file to direct the messages to the desired output device or file. 


The debug option causes the contents of all control packets sent or recaved to be logged— that is, all LCP, PAP, CH AP, or 
IPCP packets. This can be useful if the PPP negotiation does not succeed. If debugging is enabled at compile time the debug 
option also causes other debugging messages to be logged. 


Debugging can also be enabled or disabled by sending a sicusri to the pppa process. T his signal acts as a toggle 


FILES 
/var/run/pppn.pid (BSD or Linux) Process-ID for pppd process on PPP interface unit n. 
/etc/ppp/pppn .pid (others) 
/etc/ppp/ip-up A program or script that is executed when the link is available for sending and 


recaving IP packets (that is, IPC P has comeup). It is executed with the 
parametersinterface-name tty-device speed local-|P-address remote-|P-address 
and with its standard input, output and error streams redirected to /dev/null. 
This program or script is executed with the same real and effective user-ID as 
pppd— that is, at least the effective user-ID and possibly the real user-1D will be 
root. T hisis so that it can be used to manipulate routes, run privileged daaenons 
(such as send-mail), and so on. Be careful that the contents of the /etc/ppp/ip-up 
and /etc/ppp/ip-down scripts do not compromise your system’s security. 

/etc/ppp/ip-down A program or script that is executed when the link isno longer available for 
sending and recaving IP packets. This script can be used for undoing the effects 
of the /etc/ppp/ip-up script. It isinvoked with the same parameters as the ip-up 
script, and the same security considerations apply because it is executed with the 
same effective and real user-ID s as pppd. 

/etc/ppp/ipx-up A program or script that is executed when the link is available for sending and 
receiving IPX packets (that is, IPXCP has come up). It is executed with the 
parametersinterface-name tty-device speed network-number |ocal-|PX-node- 
address remote-|PX-node-address local-IPX-routing-protocol remote-|PX- 
routing-protocol local-IPX-router-name remote-!PX-router-name ipparam pppd- 
pid and with its standard input, output, and error streams redirected to 
/dev/null. 

Thelocal-1PX-routing-protocol and remote-1PX-routing- protocol field may be 
one of the following: 


pppstats 


NONE to indicate that there is no routing protocol. rip to indicate that RIP/SAP 
should be used. nLsp to indicate that N oval N LSP should be used. rp NnLsP to 
indicate that both RIP/SAP and NLSP should be used. 


This program or script is executed with the same real and effective user-ID as 
pppd— that is, at least the effective user-ID and possibly the real user-1D will be 
root. T hisis so that it can be used to manipulate routes, run privileged daaenons 
(such aS ripd), and so on. Be careful that the contents of the /etc/ppp/ipx-up and 
/etc/ppp/ipx-down scripts do not compromise your system's security. 

/etc/ppp/ipx- down A program or script that is executed when the link isno longer available for 
sending and recaving|PX packets. This script can be used for undoing the 
effects of the /etc/ppp/ipx-up script. It is invoked with the same parameters as 
the ipx-up script, and the same security considerations apply because it is 
executed with the same effective and real user-|D s as pppd. 


/etc/ppp/pap-secrets Usernames, passwords, and IP addresses for PAP authentication. 

/etc/ppp/chap-secrets N ames, secrets, and IP addresses for CH AP authentication. 

/etc/ppp/options System default options for pppd, read before user default options or command- 
line options. 

~/.ppprc User default options, read before command-line options. 

/etc/ppp/options.ttyname System default options for the serial port being used, read afte’ command-line 
options. 

SEE ALSO 

RFC 1144 Jacobson, V. Compressing T C P/IP headers for low-speed serial links. February 
1990. 

RFC 1321 Rivest, R. TheM D5 M essage-D igest Algorithm. April 1992. 

RFC 1332 McGregor, G. PPP Internet Protocol Control Protocol (IPCP). M ay 1992. 

RFC 1334 Lloyd, B.; Simpson, W .A. PPP authentication protocols. 1992 Octobe. 

RFC 1548 Simpson, W.A. T hePoint-to-Point Protocol (PPP). D ecenber 1993. 

RFC 1549 Simpson, W.A. PPP in HDLC Framing. D ecember 1993. 

NOTES 

The following signals have the specified effect when sent to the pppd process: 

SIGINT, SIGTERM T hese signals cause pppd to terminate the link (by closing LCP), restore the serial 
device settings, and exit. 

SIGHUP This signal causes pppa to terminate the link, restore the serial device settings, and 


close the serial device. If the persist option has been specified, pppd tries to 
reopen the serial device and start another connection. O therwise, pppa exits. 


SIGUSR2 This signal causes pppa to renegotiate compression. T his can be useful to re 
enable compression after it has been disabled as a result of a fatal decompression 
error. W ith the BSD Compress scheme, fatal decompression errors generally 
indicate a bug in one or another implementation. 


AUTHORS 
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pppstats 


pppstats— Print PPP statistics. 
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SYNOPSIS 


pppstats [ -v ][-r ][-c ][-i secs ][unit# ] 


DESCRIPTION 
pppstats prints PPP-related statistics. 


The -v flag causes pppstats to display additional statistics, such asthe number of packets tossed (that is, which theV] TCP 
header decompression code rejected). 


The -r flag causes pppstats to display the overall packet compression rate. T he rate value is between @ and 1, with a meaning 
that the data is incompressible. 


The -c flag is used to specify an alternate display mode that shows packet compression statistics: the number of packets and 
bytes uncompressed (that is, before compression or after decompression), compressed, and incompressible (packets that did 
not shrink on compression and were transmitted uncompressed), and the recent compression rate. This rate reflects the 
recent performance of the compression code rather than the overall rate the code compression was enabled. 


The -i flag is used to specify the interval between printouts. The default is 5 seconds. 
unit # Specifies which interface to use for gathering statistics. 
2 May 1995 


prunehistory 


prunehistory— Remove filenames from U set history file. 


SYNOPSIS 


prunehistory [ -f filename ][-p ][input ] 


DESCRIPTION 


prunehistory modifies the history(5) text fileto renovea set of filenames from it. The filenames are removed by overwriting 
them with spaces so that the size and position of any following entries do not change 


prunehistory reads the named input file or standard input if no file is given. T he input is taken as a set of lines. Blank lines 
and lines starting with a number sign (#) are ignored. All other lines should consist of a M essage-D followed by zero or more 
filenames. prunehistory usually complains about lines that do not follow this format. If the -p flag is used, then the program 
silently prints any invalid lines on its standard output. (Blank lines and comment lines are also passed through.) This can be 
useful when prunehistory isused asa filter for othe programs such as reap. 


TheM essage!D is used as the dbz(3) key to get an offset into the text file If no filenames are mentioned on the input line, 
then all filenames in the text are ranoved. If any filenames are mentioned, they are converted into the history file notation. If 
they appear in the line for the specified M essage-ID , they are renoved. 


The default name of the history fileis /news/1ib/history; to specify a different name, use the -+ flag. 
Because inna(8) only appends to the text file prunehistory does not need to have any interaction with it. 
It is a good idea to delete purged entries and rebuild the dbz database every so often by using a script such as the following: 


ctlinnd throttle "Rebuilding history database" 
cd /news/1lib 

awk 'NF > 2 { 

printf "%s\t%s\t%s" ,$1,$2,$3; 

for (i = 4; i <= NF; i++) 

printf " %s", $i; 

print "\n"; 

}' <history >history.n 

if makehistory -r -f history.n ; then 


quotacheck 


mv history.n history 

mv history.n.pag history.pag 

mv history.n.dir history.dir 

else 

echo 'Problem rebuilding history; old file not replaced' 
fi 

ctlinnd go "Rebuilding history database" 


N ote that this keaps no record of expired articles. 
HISTORY 


Written by Rich $alz (rsalzeuunet.uu.net) for InterN etN ews. 


SEE ALSO 


dbz(3), history(5), inna(8) 


quotacheck 


quotacheck— Scan a filesystem for disk usages. 


SYNOPSIS 


quotacheck [-g] [-u] [-v] -a 
quotacheck [-g] [-u] [-v] filesys ... 


DESCRIPTION 


quotacheck performs a filesystem scan for usage of files and directories, used by either user or group. The output is the quota 
file for the corresponding filesystem. By default, the names for these files are 

A user scan quota.user 

A group scan quota.group 


Theresulting file consists of a struct dqb1k for each possibleID up to the highest existing UID or GID and contains the 
values for the disk file and block usage and possibly excess time for these values. (For definitions of struct dqblk, See 
linux/quota.h.) 


quotacheck should be run each time the system boots and mounts non-valid filesystems. T his is most likely to happen after a 
system crash. 
T he speed of the scan decreases with the amount of directories increasing. The time needed doubles when disk usage is 


doubled as well. A 100M B partition used for 94 percent is scanned in one minute thesame partition used for 50 percent is 
donein 25 seconds. 


OPTIONS 
“V This way, the program will give some useful information about what it is doing, plus 
some fancy stuff. 
-d This means debug. It will result in alot of information that can be used in debugging 
the program. T he output is very verbose and the scan will not be fast. 
-U This flag tdls the program to scan the disk and to count the files and directories used by 
acetain UID. Thisisthe default action. 
-g This flag forces the program to count the files and directories used by acettain GID. 
NOTE 


checkquota should only be run as superuser. N on-privileged users are presumably not allowed to read all the directories on 
the given filesystem. 
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SEE ALSO 


quota(1), quotact1(2), fstab(5), quotaon(8), quotaoff(8), edquota(8), repquota(8), fsck(8), efsck(8), e2fsck(8), xfsck(8) 


FILES 
quota.user 
quota.group 


/etc/fstab 


AUTHOR 


Edvard T uinder (v892231@si.hhs.nl, etuinder@delirium.nl.mugnet.org), M arco van Wieringen (v892273@si.hhs.n1, 
mvw@mcs.nl.mugnet.org). 


21 August 1993 


quotaon, quotaof f 


quotaon, quotaoff—T urn filesystem quotas on and off. 


SYNOPSIS 


/usr/etc/quotaon [ -vug ] filesystem... 
/usr/etc/quotaon [ -avug ] 


/usr/etc/quotaoff [ -vug ] filesystem... 
/usr/etc/quotaoff [ -avug ] 


DESCRIPTION 


quotaon announces to the system that disk quotas should be enabled on one or more filesystems. T he filesystem quota files 
must be present in the root directory of the specified filesystem and be named quota.user for user quota or quota.group for 
group quota. 


quotaoff announcesto the system that filesystems specified should have any disk quotas turned off. 


OPTIONS 





quotaon 
-a All filesystems in /etc/fstab marked read-write with quotas will have thar quotas 
turned on. Thisis usually used at boot time to enable quotas. 
“V Display a message for each filesystem where quotas are turned on. 
-U M anipulate user quotas. T hisis the default. 
-g M anipulate group quotas. 
quotaotf 
-a Forceall filesystensin /etc/fstab to havetheir quotas disabled. 
“V Display a message for each filesystem affected. 
-u M anipulate user quotas. T hisis the default. 
-g M anipulate group quotas. 
FILES 
quota.user User quota file at the filesysten root 
quota.group Group quota file at the filesystem root 


/etc/fstab D efault filesystems 


8 June1993 


SEE ALSO 


quotact1(2), fstab(5) 


rarp 
rarp— M anipulate the systten RARP table 
SYNOPSIS 


rarp [-v] [-t type] -a [hostname] 
rarp [-v] -d hostname ... 
rarp [-v] [-t type] -s hostname hw addr 


DESCRIPTION 


rarp Manipulates the kernel’s RARP table in various ways. T he primary options are clearing an address mapping entry and 
manually setting up one For debugging purposes, the rarp program also allows a complete dump of theRARP table. 


OPTIONS 
“V Tell the user what is going on by being verbose 
-t type W hen setting or reading the RARP table, this optional parameter tells rarp which class 
of entries it should check for. T he default value of this parameter is ether (hardware 
code 0x01 for IEEE 802.3 10M bps Ethernet). O ther values might include network 
technologies such as AX.25 (ax25). 
-a [hostname ] Shows the entries of the specified hosts. If thehost name parameter is not used, all entries 
are displayed. 
-d hostname Remove the entries of the specified host. T his can be used if the indicated host is 
brought down, for example 
-s hostname hw_addr Create an RARP address mapping entry for host host name with hardware address set to 
hw_addr Class, but for most classes, you can assume that the usual presentation can be 
used. For the Ethernet class, this is 6 bytes in hexadecimal, separated by colons. 
FILES 
/proc/net/rarp 
AUTHORS 


RossD. Martin (martin@trcsun3.eas.asu.edu), Fred N. van Kempen (waltje@uwalt.n1.mugnet.org). 
11 June1994 


rdev 


rdev— Query/set image root device, swap device, RAM disk size, or video mode 


SYNOPSIS 


rdev [ -rsvh ] [ -o offset Jf[image [ value [ offset ]]] 
rdev [ -o offset ][image [ root_device [ offset ]]] 
swapdev [ -o offset J[image [ swap_device [ offset ]]] 
ramsize [ -o offset J[image [ size [ offset ]]] 
vidmode [ -o offset ][image [ mode [ offset ]]] 
rootflags [ -o offset Jf[image [ flags [ offset ]]] 
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DESCRIPTION 


With no arguments, rdev outputs an /etc/mtab line for the current root filesystem. With no arguments, swapdev, ramsize, 
vidmode, and rootflags print usage information. 


In a bootable image for the Linux kernd, there are several pairs of bytes that specify the root device, the video mode thesize 
of the RAM disk, and the swap device. T hese pairs of bytes, by default, begin at offset 504 (decimal) in the kernel image: 

498 Root flags 

(500 and 502 Reserved) 

504 RAM Disk Size 

506 VGA Mode 

508 Root D evice 

(510 Boot Signature) 


rdev Changes these values. 
Typical values for the image parameter, which is a bootable Linux kernel image, are as follows: 


/vmlinux 
/vmlinux.test 
/vmunix 
/vmunix.test 
/dev/fd0 
/dev/fd1 


When using the rdev or swapdev commands, the root device or swap device parameter are as follows: 


/dev/hda[1-8] 
/dev/hdb[1-8] 
/dev/sda[1-8] 
/dev/sdb[1-8] 


For the ramsize command, the size parameter specifiesthe size of theRAM disk in kilobytes. 


For the rootflags command, thef!ags parameter contains extra information used when mounting root. Currently, the only 
effect of these flags is to force the kernel to mount the root filesystem in read-only mode iff! ags isnonzero. 


For the vidmode command, the mode parameter specifies the video mode: 


-3 Prompt 
-2 Extended VGA 
“1 Norma VGA 


0 Asif @ was pressed at the prompt 
1 Asif 1 was pressed at the prompt 
2 Asif 2 was pressed at the prompt 
n Asif n was pressed at the prompt 


If the value is not specified, the image is examined to determine the current settings. 


OPTIONS 
-S Causes rdev to act like swapdev. 
r Causes rdev to act like ramsize. 
-R Causes rdev to act like rootflags. 
“V Causes rdev to act like vidmode. 


-h Provides hdp. 
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The user interface is cumbersome, non-intuitive, and should probably be rewritten from scratch, allowing multiple kernel 
image parameters to be changed or examined with a single command. 


BUGS 


For historical reasons, there are two methods for specifying alternative values for the offset. 


If LILO is used, rdev isno longer needed for setting the root device and the VGA mode because the parameters that rdev 
modifies can be set from the LILO prompt during a boot. H owever, rdev is still needed at this time for setting the RAM disk 
size. Users are encouraged to find the LILO documentation for more information and to useLILO when booting ther 
systems. 


AUTHORS 


Originally by Werner Almesberger (almesber@nessie.cs.id.ethz.ch). M odified by Peter M acD onald 
(pmacdona@sanjuan.UVic.CA). rootflags support added by Steohen T weedie (sct@dcs.ed.ac.uk). 


Linux 0.99, 20 N ovember 1993 


renice 


renice— Alter priority of running processes. 


SYNOPSIS 


renice priority [[-p] pid ...] [[ -g] pgrp .--] [[-u] user ...] 


DESCRIPTION 
renice alters the scheduling priority of oneor morerunning processes. T he following “who” parameters are interpreted as 
process|D s, process group ID 5, or user namé. reniceing a process group causes all processes in the process group to have 
their scheduling priority altered. reniceing a user Causes all processes owned by the user to have their scheduling priority 
altered. By default, the processes to be affected are specified by their process ID s. 


O ptions supported by renice: 


-g Forcewho parametess to be interpreted as process group IDs. 
-U Forcethe who parameters to be interpreted as usernames. 
-p Reset the who interpretation to be (the default) process IDs. 


The following example changes the priority of process |D s 987 and 32 and all processes owned by users daemon and root: 
renice +1 987 -u daemon root -p 32 

Users other than the superuser can only alter the priority of processes they own and can only monotonically increase their 
“nice value” within the range @ to pr1o_MAx (20). (This prevents overriding administrative fiats.) T he superuser can alter the 
priority of any process and set the priority to any value in the range PrRIo_MIN (-20) to pRIO_MAX. Useful priorities are 20 (the 
affected processes run only when nothing else in the system wants to), o (the “base” scheduling priority), and anything 
negative (to make things go very fast). 


FILES 


/etc/passwd to map usernames to user 1D s 


SEE ALSO 


getpriority(2), setpriority(2) 


BUGS 


N on-superusers cannot increase scheduling priorities of their own processes, even if they were the ones that decreased the 
prioritiesin the first place 
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HISTORY 
The renice command appeared in BSD 4.0. 
BSD 4, 9 June1993 





repquota 
repquota— Summarize quotas for a filesystem. 
SYNOPSIS 
/usr/etc/repquota [ -vug ] filesystem... 
/usr/etc/repquota [ -avug ] 
DESCRIPTION 
repquota prints a summary of the disk usage and quotas for the specified filesystems. For each user, the current number of 


files and amount of space (in kilobytes) is printed, along with any quotas created with edquota(8). 


OPTIONS 
“a Report on all filesystems indicated in /etc/fstab to be read-write with quotas. 
“V Report all quotas even if there is no usage. 
-g Report quotas for groups. 
-U Report quotas for users. Thisis the default. 


Only the superuser can view quotas that are not their own. 


FILES 
quotas Quota file at the filesystem root 
etc/fstab D efault filesystems 


SEE ALSO 


quota(1), quotact1(2), edquota(8), quotacheck(8), quotaon(8) 
8 June1993 


rexecd 


rexecd— Remote execution server. 


SYNOPSIS 


rexecd 


DESCRIPTION 
rexecd is the server for the rexec(3) routine. T he server provides remote execution facilities with authentication based on 
usernames and passwords. 


rexecd listens for service requests at the port indicated in the exec service specification; see services(5). When aservice 
request is received, the following protocol is initiated: 


1. Theserver reads characters from the socket up to a null \@ byte. The resultant string is interpreted as an ASCII number, 
base 10. 
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2. If thenumber received in Step 1 is nonzero, it is interpreted asthe port number of a secondary stream to be used for the 

stderr. A second connection is then created to the specified port on the client’s machine 

A null-terminated username of at most 16 characters is retrieved on theinitial socke. 

A null-terminated, unencrypted password of at most 16 characters is retrieved on the initial socket. 

5. A null-terminated command to be passed to a shdl isretrieved on the initial socket. The length of the command is 
limited by the upper bound on the size of the system’s argument list. 

6. rexecd then validates the user asis doneat login time and, if the authentication was successful, changes to the user’s 
home directory and establishes the user and group protections of the user. If any of these steps fail, the connection is 
aborted with a diagnostic message returned. 

7. A null byte isreturned on the initial socket and the command line is passed to the normal login shal of the user. The 
shdl inherits the network connections established by rexecd. 


DIAGNOSTICS 
Except for the last one listed, all diagnostic messages are returned on theinitial socket, afte’ which any network connections 
are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in Step 7 upon successful completion of all 
the steps prior to the command execution). 


2m 


username too long The name is longer than 16 characters. 
password too long The password is longer than 16 characters. 
command too long The command line passed exceeds the size of the argument list (as configured into the 
system). 
Login incorrect. N o password file entry for the username existed or the wrong password was supplied. 
No remote directory. The chdir command to the home directory failed. 
Try again. A fork by the server failed. 
<shellname>: ... Theuser’s login shal could not be started. T his message is returned on the connection 
associated with the stderr and is not preceded by a flag byte 
SEE ALSO 
rexec(3) 
BUGS 
A facility to allow all data and password exchanges to be encrypted should be present. 
HISTORY 


The rexecd command appeared in BSD 4.2. 
BSD 4.2, 16 March 1991 


rlogind 


rlogind— Remote login server. 


SYNOPSIS 
rlogind [-aln] 
DESCRIPTION 


rlogind is the server for the rlogin(1) program. T he server provides a renote login facility with authentication based on 
privileged port numbers from trusted hosts. 
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Options supported by rlogina: 


“a Ask hostname for verification. 

“1 Prevent any authentication based on the user's . rhosts file unless the user is logging in 
as the superuser. 

-n Disable keep-alive messages. 


rlogind listens for service requests at the port indicated in the “login” service specification; see services(5). When aservice 

request is received, the following protocol is initiated: 

1. Theserver checks the client’s source port. If the port isnot in the range 512-1023, the server aborts the connection. 

2. Theserver checks the client’s source address and requests the corresponding hostname (see gethostbyaddr(3), hosts(5), 
and namea(8)). If the hostname cannot be determined, the dot-notation representation of the host address is used. If the 
hostname isin the same domain as the server (according to the last two components of the domain name), or if the -a 
option is given, the addresses for the hostname are requested, verifying that the name and address correspond. N ormal 
authentication is bypassed if the address verification fails. 

Oncethe source port and address have been checked, rlogind proceeds with the authentication process described in rsha(8). 

It then allocates a pseudo terminal (see pty(4)) and manipulates file descriptors so that the slave half of the pseudo terminal 

becomes the stdin, stdout, and stderr for alogin process. The login process is an instance of the 1ogin(1) program, invoked 

with the -¢ option if authentication has succeeded. If automatic authentication fails, the user is prompted to login asif ona 
standard terminal line 

The parent of the login process manipulates the master side of the pseudo terminal, operating as an intermediary between the 

login process and the client instance of the riogin program. In normal operation, the packet protocol described in pty(4) is 

invoked to provide S/Q type facilities and propagate interrupt signals to the remote programs. T he login process propagates 
the client terminal's baud rate and terminal type, as found in the environment variable TERM; see environ(7). The screen or 
window size of the terminal is requested from the client, and window size changes from the client are propagated to the 
pseudo terminal. 

Transport-levd keep-alive messages are enabled unless the -n option is present. T he use of Keep-alive messages allows sessions 

to be timed out if the client crashes or becomes unreachable 


DIAGNOSTICS 


All initial diagnostic messages are indicated by a leading byte with a value of 1, after which any network connections are 
closed. If there are no errors before login is invoked, a null byte is returned asin indication of success. 


Try again. A fork by the server failed. 


SEE ALSO 


login(1), ruserok(3), rshd(8) 


BUGS 


The authentication procedure used here assumes the integrity of each client machine and the connecting medium. This is 
insecure but is useful in an “open” environment. 


A facility to allow all data exchanges to be encrypted should be present. 
A more extensible protocol should be used. 


HISTORY 
Therlogind command appeared in BSD 4.2. 
BSD 4.2, 16 March 1991 
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route 


route— Show/manipulate the IP routing table. 


SYNOPSIS 


route [ -vn ] 

route [ -v ] add [ -net | -host ] XXXX [gw GGGG] [metric MMMM] [netmask NNNN] 
[mss NNNN] [window NNNN] [dev DDDD] 

route [ -v ] del XXxXXx 


DESCRIPTION 
route manipulates the kernel’s | P routing table. Its primary use isto set up static routes to specific hosts or networks viaan 
interface after it has been configured with the ifconfig(8) program. This version of route isintended solely for use with 
kernd versions 0.99p|14n and newer kernels. 


OPTIONS 

(none) Prints out the kernd routing table, listing destination address, gateway, netmask for 
route (“Genmask”), flags (U =U p, H =H ost, c =G ateway, p =dynamic, m =M odified), 
Metric (currently not supported), Ref, Use, and Iface (which device the route maps to). 

-n Same as previous but shows numerical addresses instead of trying to determine symbolic 
host names. 

“V A flag for verbose (not actually used). 

del XXXXx D eletes the route associated with the destination address xxxx. 

add[-net ! -host ] XXXX [gw GGGG] Adds arouteto theIP address xxxx. Theroute is anetwork route if the -net modifier is 

[metric MMMM] [netmask NNNN] used or xxxx isfound in /etc/networks by the getnetbyname() library function and no 

[dev DDDD] -host modifier is used. 


The gw GGGG argument means that any IP packets sent to this address will be routed 
through the specified gateway. N ote The specified gateway must be reachable first. T his 
usually means that you have to set up a static route to the gateway beforehand. 
Themetric mum modifier isnot yet implemented (and with the -v option will actually 
print a warning). 

The netmask NNNN modifier specifies the netmask of the route to be added. T his only 
makes sense for anetwork route and when the address xxxx actually makes sense with 
the specified netmask. If no netmask is given, route guesses it instead, so for most 
normal setups, you won't need to specify a netmask. 

Themss NNNN modifier specifies the TCP mss for the route to be added. T hisis usually 
used only for fine optimization of routing setups. 

The window NNNN modifier specifies the TC P window for the route to be added. This is 
typically only used on AX.25 networks and with drivers unable to handle back-to-back 
frames— such asthe 3c501 or D E600. 

The dev 0000 modifier forces the route to be associated with the specified device because 
the kernd will otherwise try to determine the device on its own (by checking already 
existing routes and device specifications and where the route is added to). In most 
normal networks, you won't need this. 

If dev DdDD isthe last option on the command line, the word dev may be omitted 
because it’s the default. O therwise, the order of the route modifiers (metric, netmask, gw, 
and dev) doesn’t matter. 
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EXAMPLES 
route add -net 127.0.0.0 Adds the normal loopback entry, using netmask 255.0.0.0 (ClassA net determined from 
the destination address) and associated with the 10 device (assuming this device was 
previously set up correctly with ifconfig(8)). 
route add -net 192.56.76.0 Adds a route to the network 192.56.76.x viaetho. TheClassC netmask modifier is not 
netmask 255.255.255.0 dev ethd really necessary here because 192.* isaClass C IP address. The word dev can be omitted 


hee 


route add default gw mango-gw Adds a default route (which will be used if no other route matches). All packets using 
this route will be gatewayed through mango-gw. T he device that will actually be used for 
that route depends on how you can reach mango-gw; the static route to mango - gw will have 
to be set up before 


route add ipx4 sl@ route add -net 1 hiScommand sequence adds the route to the ipx4 host via the SLIP interface 
192.57.66.0 netmask 255.255.255.0 (assuming that ipx4 istheSLIP host) and then adds the nét 192.57.66.0 to be gatewayed 
gw ipx4 through that host. 


FILES 
/proc/net/route 
/etc/networks 


/etc/hosts 


SEE ALSO 


ifconfig(8) 


HISTORY 
route for Linux was originally written by Fred N. van Kanpen (waltje@uwalt.nl.mugnet.org) and then modified by Johannes 
Stille and Linus Torvalds for pl15. Alan Cox added themss and window options for Linux 1.1.22. 


14 June1994 


routed 


routed— N etwork routing daemon. 


SYNOPSIS 


routed [-d] [-g] [-q] [-s] [-t] [logfile] 


DESCRIPTION 


routed is invoked at boot time to manage the network routing tables. T he routing daemon uses a variant of the Xerox NS 
Routing Information Protocol in maintaining up-to-date kernd routing table entries. It used a generalized protocol capable 
of use with multiple address types but is currently used only for Internet routing within a cluster of networks. 


In normal operation, routed listens on the udp(4) socket for the route(8) service (See services(5)) for routing information 
packets. If the host is an internetwork router, it periodically supplies copies of its routing tables to any directly connected 
hosts and networks. 


W hen routed is started, it uses the STOCGIFCONF ioct1(2) to find those directly connected interfaces configured into the systen 
and marked “up” (the software loopback interface is ignored). If multiple interfaces are present, it is assumed that the host 
will forward packets between networks. routed then transmits a request packet on each interface (using a broadcast packet if 
the interface supports it) and enters a loop, listening for request and response packets from other hosts. 


routed 


W hen a request packet is received, routed formulates a reply based on the information maintained in its internal tables. The 
response packet generated contains a list of Known routes, each marked with a “hop count” metric (a count of 16, or greater, 
is considered “infinite’). The metric associated with each route returned provides ametric rdative to the sender. 


Response packets received by routed are used to update the routing tables if one of the following conditions is satisfied: 


No routing table entry exists for the destination network or host, and the metric indicates the destination is “reachable” 
(the hop count is not infinite). 

The source host of the packet is the same as the router in the existing routing table entry. T hat is, updated information is 
being received from the very internetwork router through which packets for the destination are being routed. 

The existing entry in the routing table has not been updated for some time (defined to be 90 seconds) and the route is at 
least as cost effective as the current route. 

T he new route describes a shorter route to the destination than the one currently stored in the routing tables; the metric 
of the new route is compared against the one stored in the table to decide this. 


When an update is applied, routed records the change in its internal tables and updates thekernel routing table. The change 
is reflected in the next response packet sent. 


In addition to processing incoming packets, routed also periodically checks the routing table entries. If an entry has not been 
updated for three minutes, the entry's metric is set to infinity and marked for deletion. D detions are delayed an additional 
60 secondsto ensure the invalidation is propagated throughout the local Interne. 


H osts acting as internetwork routers gratuitously supply thar routing tables every 30 seconds to all directly connected hosts 
and networks. T he response is sent to the broadcast address on nets capable of that function, to the destination address on 
point-to-point links, and to the router’s own address on other networks. The normal routing tables are bypassed when 
sending gratuitous responses. T he receotion of responses on each network is used to determine that the network and 
interface are functioning correctly. If no response is receaved on an interface another route may be chosen to route around 
the interface, or the route may be dropped if no alternative is available. 


Options supported by routed: 


-d Enable additional debugging information to be logged, such as bad packets received. 

-g This flag is used on internetwork routers to offer a route to the “default” destination. 
Thisis typically used on a gateway to the Internet or on a gateway that uses another 
routing protocol whose routes are not reported to othe’ local routers. 

-s Supplying this option forces routed to supply routing information whether it is acting as 
an internetwork router or not. T his is the default if multiple network interfaces are 
present or if a point-to-point link isin use 

-q Thisis the opposite of the -s option. 

-t If the -t option is specified, all packets sent or received are printed on the standard 
output. In addition, routed will not divorce itsdf from the controlling terminal so that 
interrupts from the keyboard will kill the process. 





Any other argument supplied is interpreted as the name of file in which routed’s actions should be logged. Thislog contains 
information about any changes to the routing tables and, if not tracing all packets, a history of recent messages sent and 
received that are related to the changed route. 


In addition to the facilities described previously, routed supports the notion of “distant” passive and active gateways. W hen 
routed is started, it reads the file to find gateways that might not be located using only information from the s1oGIFconFioct1 
(2). Gateways specified in this manner should be marked passive if they are not expected to exchange routing information, 
whereas gateways marked active should be willing to exchange routing information (that is, they should have a routed process 
running on the machine). Routes through passive gateways are installed in the kernel’s routing tables once upon startup. 
Such routes are not included in any routing information transmitted. Active gateways are treated equally to network 
interfaces. Routing information is distributed to the gateway, and if no routing information is received for a period of the 
time, the associated route is deleted. G ateways marked external are also passive but are not placed in the kernd routing table 
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nor are they included in routing updates. The function of external entries is to inform routed that another routing process 
will install such a route and that alternate routes to that destination should not be installed. Such entries are only required 
when both routers might learn of routes to the same destination. 


The /etc/gateways is comprised of a series of lines, each in the following format: 
<net;host> namel gateway name2 metric value <passive;active,external> 
The net or host Keyword indicates if the route is to a network or specific host. 


name isthename of the destination network or host. T his can bea symbolic name located in or known to the name serve if 
started after named(8) or an Internet address specified in “dot” notation; see inet(3). 


name2 isthenameor address of the gateway to which messages should be forwarded. 
val ue isametric indicating the hop count to the destination host or network. 


Oneof the keywords passive, active, OF external indicates if the gateway should be treated as passive or active (as described 
previously) or whether the gateway is external to the scope of the routed protocol. 


Internetwork routers that are directly attached to the ARPAnéet or M ilnet should use the Exterior G ateway Protocol (EGP) to 
gather routing information rather than use a static routing table of passive gateways. EGP isrequired in order to provide 
routes for local networks to the rest of the Internet system. Sites needing assistance with such configurations should contact 
the Computer Systems R esearch Group at Berkeley. 


FILES 


/etc/gateways for distant gateways 
SEE ALSO 

udp(4), icmp(4), XNSrouted(8), htable(8) 

Internet Transport Protocols, XSIS 028112, Xerox System Integration Standard 
BUGS 


The kernel’s routing tables may not correspond to those of routed when redirects change or add routes. routed should note 
any redirects received by reading the IC M P packets received via a raw socket. 


routed should incorporate othe routing protocols, such as Xerox NS, xnSrouted(8), and EGP . Using separate processes for 
each requires configuration options to avoid redundant or competing routes. 


routed should listen to intelligent interfaces, such as an IM P, to gather more information. It does not always detect 
unidirectional failures in network interfaces (such as when the output side fails). 


HISTORY 
The routed command appeared in BSD 4.2. 
BSD 4.2, 16 March 1991 


rpc. rusersd 


rpc.rusersd— Logged-in users server. 


SYNOPSIS 


/usr/libexec/rpc.rusersd 


DESCRIPTION 


rpc.rusersd iS a server that returns information about users currently logged in to the systen. 


rpcinfo 


The currently logged-in users are queried using therusers(1) command. Therpc.rusersd daanon is usually invoked by 
ineta(8). 


rpc.ru 


SEE ALSO 


rusers 


sersd usesan RPC protocol defined in /usr/include/rpcsve. 


(1), who(1), w(1), ineta(8) 
BSD 4.3, 7 June1993 


rpc. rwalld 


rpc. rwalld— W rite messages to users currently logged in to the server. 


SYNOPSIS 


/usr/1 


ibexec/rpc.rwalld 


DESCRIPTION 


rpc.rwalld isa server that will send a message to users currently logged in to the system. T his server invokes thewa11(1) 


comm 


M essages are sent to this server by the rwal1(1) command. Therpc.rwalid daemon is usually invoked by ineta(8). 


and to actually write the messages to the system. 


rpc. rwalld uses an RPC protocol defined in /usr/include/rpcsvc/rwall.x. 


SEE ALSO 


rwall( 


1), wal1(1), ineta(8) 
BSD 4.3, 7 June1993 


rpcinfo 





rpcinfo— Report RPC information. 
SYNOPSIS 
rpcinfo -p [host ] 
rpcinfo [-n portnum] -u host program [version] 
rpcinfo [-n portnum] -t host program [version] 
rpcinfo -b program version 
rpcinfo -d program version 
DESCRIPTION 
rpcinfo makes an RPC call to an RPC server and reports what it finds. 
OPTIONS 
-p Probe the port mapper on host and print alist of all registered RPC programs. If host is 
not specified, it defaults to the value returned by hostname(1). 
-U M akean RPC call to procedure 0 of program on the specified host using UDP and 
report whether a response was received. 
-t M akean RPC call to procedure 0 of program on the specified host using TCP and report 


whether a response was rece ved. 
Use port num astheport number for the -t and -u options instead of the port numbe" 
given by the port mapper. 
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-b M ake an RPC broadcast to procedure 0 of the specified program and version using UD P 
and report all hosts that respond. 
-d D elete registration for the RPC service of the specified program and version. T his option 


can be exercised only by the superuser. 


The program argument can be either a name or anumber. If aversion is specified, rpcinfo attempts to call that version of the 
specified program. O therwise, rpcinfo attempts to find all the registered version numbe’s for the specified program by calling 
version 0 (which is presumed not to exist; if it does exist, rpcinfo attempts to obtain this information by calling an extremely 
high version number instead) and attempts to call each registered version. N ote that the version number is required for -b 
and -d options. 

EXAMPLES 
To show all the RPC services registered on the local machine, use 
rpcinfo -p 
To show all of the RPC services registered on the machine named klaxon, use 
rpcinfo -p klaxon 
To show all machines on the local net that are running the Yellow Pages service, use 


rpcinfo -b ypserv ‘version’ -- unig 





‘version’ iSthe current Yellow Pages version obtained from the results of the -p switch above 


To ddete the registration for version 1 of thewal1d service, use 
rpcinfo -d walld 1 


SEE ALSO 
rpc(5), portmap(8), RPC Programming Guide 


BUGS 


In releases prior to SunOS 3.0, the N a@work File System (N FS) did not register itsdf with the port mapper; rpcinfo cannot 
be used to make RPC calls to the N FS server on hosts running such rdeases. 


17 December 1987 


rquotad, rpc.rquotad 


rquotad, rpc.rquotad— Remote quota server. 


SYNOPSIS 


/usr/etc/rpc.rquotad 


DESCRIPTION 


rquotad iS an rpc(3N ) server that returns quotas for a user of alocal filesystem that is mounted by a ranote machine over the 
NFS. The results are used by quota(1) to display user quotas for remote filesystems. The rquotad daemon is usually started at 
boot time from the rc.net script. 


FILES 


quotas Quota file at the filesystem root 
SEE ALSO 
quota(1), rpc(3N ), nfs(4P), services(5) ineta(8C) 
17 December 1987 


rhd 


rshd 


rshd— Remote shal server. 


SYNOPSIS 


rshd [-alnL] 


DESCRIPTION 


The rsha server is the server for the rema(3) routine and, consequently, for the rsh(1) program. The server provides remote 
execution facilities with authentication based on privileged port numbers from trusted hosts. 


The rsha server listens for service requests at the port indicated in the cma service specification; see services(5). When a 
service request is received, the following protocol is initiated: 


1. Theserver checks the client’s source port. If the port isnot in the range 512-1023, the server aborts the connection. 

2. Theserver reads characters from the socket up to anull (\o) byte. The resultant string is interpreted as an ASCII 
number, base 10. 

3. If thenumber received in Step 2 is nonzero, it is interpreted asthe port number of a secondary stream to be used for the 
stderr. A second connection is then created to the specified port on the client's machine T he source port of this second 
connection is also in the range 512-1023. 

4. Theserver checks the client’s source address and requests the corresponding hostname (see gethostbyaddr(3), hosts(5), 
and namea(8)). If the hostname cannot be determined, the dot-notation reoresentation of the host address is used. If the 
hostname isin the same domain as the server (according to the last two components of the domain name), or if the -a 
option is given, the addresses for the hostname are requested, verifying that the name and address correspond. If address 
verification fails, the connection is aborted with the message, Host address mismatch. 

5. A null-terminated username of at most 16 characters is retrieved on theinitial socket. This username is interpreted as 
the user identity on the client’s machine. 

6. A null-terminated username of at most 16 characters is retrieved on the initial socket. This username is interpreted asa 
user identity to use on the server's machine 

7. Anull-terminated command to be passed to a shdl isretrieved on the initial socket. The length of the command is 
limited by the upper bound on the size of the system’s argument list. 

8. rshd then validates the user using ruserok(3), which uses the file and the file found in the user's home directory. The -1 
option prevents ruserok(3) from doing any validation based on the user's . rhosts file, unless the user is the superuser. 

9. A null byte isreturned on the initial socket and the command line is passed to the normal login shal of the user. The 
shal inherits the network connections established by rshd. 


Transport-leved keep-alive messages are enabled unless the -n option is present. T he use of Keep-alive messages allows sessions 
to be timed out if the client crashes or becomes unreachable 





The -L option causes all successful accesses to be logged to syslogd(8) as auth. info messages and all failed accesses to be 
logged as auth. notice. 


DIAGNOSTICS 


Except for the last one listed, all diagnostic messages are returned on theinitial socket, after which any network connections 
are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in Step 9 upon successful completion of all 
the steps prior to the execution of the login shal). 


Locuser too long. Thename of the user on the client’s machineis longer than 16 characters. 

Ruser too long. The name of the user on the ranote machine is longer than 16 characters. 

Command too long. The command line passed exceeds the size of the argument list (as configured into the 
system). 

Login incorrect. No password file entry for the username existed. 


Remote directory. The chdir command to the home directory failed. 
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Permission denied. The authentication procedure described previously failed. 
Can't make pipe. The pipe needed for the stderr wasn’t created. 
Can't fork; try again. A fork by the server failed. 
<shellname>: ... Theuser’s login shal could not be started. T his message is returned on the connection 
associated with the stderr and is not preceded by a flag byte 
SEE ALSO 
rsh(1), remd(3), ruserok(3) 
BUGS 


The authentication procedure used here assumes the integrity of each client machine and the connecting medium. This is 
insecure but is useful in an “open” environment. 


A facility to allow all data exchanges to be encrypted should be present. 
A more extensible protocol (such as Telnet) should be used. 
BSD 4.2, 30 April 1991 


rwhod 


rwhod— System status server. 


SYNOPSIS 


rwhod 


DESCRIPTION 


rwhod isthe server that maintains the database used by the rwho(1) and ruptime(1) programs. Its operation is predicated on 
the ability to broadcast messages on a network. 


rwhod Operates as both a producer and consume of status information. As a producer of information, it periodically queries 
the state of the systen and constructs status messages that are broadcast on anetwork. As a consumer of information, it 
listens for other rwhod servers’ status messages, validating them and then recording them in a collection of files located in the 
directory. 


The server transmits and receives messages at the port indicated in the rwho service specification; see services(5). The 
messages sent and received are of the form: 


struct outmp { 

char out_line[8]; /* tty name */ 
char out_name[8]; /* user id */ 
long out_time; /* time on */ 

hs 


struct whod { 
char wd_vers; 
char  wd_type; 
char wd_fill[2]; 
int wd_sendtime; 
int wd_recvtime; 
char wd_hostname[32]; 
int wd_loadav[3]; 
int wd_boottime; 
struct whoent { 

struct outmp we_utmp; 
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int we_idle; 
} wd_we[1024 / sizeof (struct whoent)]; 
}; 


All fidds are converted to network byte order prior to transmission. The load averages are as calculated by thew(1) program 
and represent load averages over the 5-, 10-, and 15-minute intervals prior to a server's transmission; they are multiplied by 
100 for representation in an integer. The hostname included is that returned by the gethostname(2) system call, with any 
trailing domain name omitted. T he array at the end of the message contains information about the users logged in to the 
sending machine. T his information includes the contents of the utmp(5) entry for each non-idle terminal line and avalue 
indicating the time in seconds since a character was last reca ved on the taminal line 


M essages received by the rwho server are discarded unless they originated at an rwho server's port. In addition, if the host’s 
name, as specified in the message, contains any unprintable ASCII characters, the message is discarded. V alid messages 
received by rwhod are placed in files named in the directory. T hese files contain only the most recent message, in the format 
described previously. 





Status messages are generated approximately once every three minutes. rwhod performs an nlist(3) every 30 minutes to guard 
against the possibility that this file is not the system image currently operating. 


SEE ALSO 


rwho(1), ruptime(1) 


BUGS 


There should bea way to rday status information between networks. Status information should be sent only upon request 
rather than continuously. People often interpret the server dying or network communication failures as a machine going 
down. 


HISTORY 
The rwhod command appeared in BSD 4.2. 


BSD 4.2, 16 March 1991 


Sendmail 


sendmail— Send mail over the Internet. 


SYNOPSIS 


sendmail [flags] [address ...] 
newaliases 

mailq [-v] 

smtpd 

bsmtp 

rung 


DESCRIPTION 


sendmail sends a message to one or more recipients, routing the message over whatever networks are necessary. sendmail does 
internetwork forwarding as necessary to deliver the message to the correct place. 


sendmail isnot intended as a user interface routine. O ther programs provide user-friendly front ends. sendmail is used only to 
ddiver preformatted messages. 


With no flags, sendmail readsits standard input up to an end-of-file or a line consisting only of asingle dot and sends a copy 
of the message found there to all the addresses listed. It determines the networks to use based on the syntax and contents of 
the addresses. 
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Local addresses are looked up in afile and aliased appropriately. Aliasing can be prevented by preceding the address with a 
backslash. U sually, the sender is not included in any alias expansions; for example, if john sends to group and group includes 
john in the expansion, then the letter will not be ddivered to john. 


Flags are 


-ba 
-bd 


-bi 
-bm 
-bp 
=bs 


-bb 
-bt 


-bv 


-bz 
-C file 


-d X 
-F fullname 


-f name 


-o xX value 


-q time 


M ident 
-R addr 
S addr 


-r name 


Go into ARPANET mode All input lines must end with aCR-LF, and all messages will 
be generated with aCR-LF at the end. Also, the From: and Sendex: fidds are examined 
for the name of the snnde. 


Run asa daemon. This requires Berkeley IPC. sendmail will fork and run in the 
background, listening on socket 25 for incoming SM TP connections. This is usually run 
from /etc/rc. 


Initialize the alias database. 
D eliver mail in the usual way (default). 
Print a listing of the queue 


Use the SM TP protocol as described in RFC 821 on standard input and output. This 
flag implies all the operations of the -ba flag that are compatible with SMTP. 


Read batched SMTP (BSM TP) commands from standard input. 


Run in address test mode. T his mode reads addresses and shows the steps in parsing; it is 
used for debugging configuration tables. 


Verify names only; do not try to collect or deliver a message V erify modeis usually used 
for validating users or mailing lists. 


Create the configuration freeze file 


Use alternate configuration file sendmail refuses to run as root if an alternate configura- 
tion file is specified. The frozen configuration file is bypassed. 


Sé& debugging value to x. 

Sé& the full name of the sender. 

Sets the name of the “from” person (the sender of the mail). - can only be used by 
trusted users (usually root, daemon, and network) or if the person you are trying to 
becomeis the same as the person you are. 

Se the hop count to v. The hop count is incremented every time the mail is processed. 
W hen it reaches a limit, the mail is returned with an error message, the victim of an 
aliasing loop. If not specified, R ecaved: lines in the message are counted. 

Don't do aliasing. 

Se option x to the specified val ue. Options are described later in this section. 
Processed saved messages in the queue at given intervals. If ti me is omitted, process the 
queue once ti me is given as atagged number, with s being seconds, m being minutes, h 
being hours, a being days, and w being weeks. For example, -qih3em or -q9am both set the 
time-out to 1 hour, 30 minutes. If ti me is specified, sendmail runsin background. T his 
option can be used safely with -ba. 

Process the queued message with the queue ID ident. 

Process the queued messages that have the string addr in one of the recipient addresses. 
Process the queued messages that have the string addr in thesender address. 

An alternate and obsolete form of the -+ flag. 

Read message for recipients. To:, Cc:, and Bcc: lines are scanned for recipient addresses. 
The Bcc: line is ddeted before transmission. Any addresses in the argument list are 
Suppressed; that is, they do not receive copies even if listed in the message header. 


Go into verbose mode. Alias expansions are announced and so on. 





sendmail 


There are also anumber of processing options that can be set. Usually, these will only be used by a system administrator. 
O ptions can be set dther on the command line using the -o flag or in the configuration file. T hese are described in detail in 
the Sendmail Installation and O peration Guide T he options are 


A file Use alternate alias file 

c On mailers that are considered “expensive” to connect to, don’t initiate immediate 
connection. T his requires queuing. 

d x Sé& the ddivery mode to x. D elivery modes are i for interactive (synchronous) ddivery, 


b for background (asynchronous) delivery, and q for queue only (actual delivery is done 
the next time the queue is run). 

D Try to automatically rebuild the alias database if necessary. 

ex Set error processing to modex. Valid modes are m to mail back the error message, w to 
“write” back the error message (or mail it back if the sender is not logged in), p to print 
the errors on the terminal (default), q to throw away error messages (only exit status is 
returned), and e to do special processing for the BerkN et. If the text of the message is 
not mailed back by modes n or w and if the sender is local to this machine, a copy of the 
message is appended to the file in the sender's home directory. 


F mode The mode to use when creating temporary files. 

f Save UN 1X-style From: lines at the front of messages. 

gN The default group 1D to use when calling mailers. 

H file The SM TP hap file 

i Do not take dots on a line by themselves as a message terminator. 

KN Checkpoint the queue file after every n successful deliveries (default is 10). This avoids 
excessive duplicate deliveries when sending to long mailing lists interrupted by system 
crashes. 

an The log level. 

m Send also to “me” (the sender) if | am in an alias expansion. 

0 If set, this message may have old style headers. If not set, this message is guaranteed to 


have new style headers (commas instead of spaces between addresses). If set, an adaptive 
algorithm is used that will correctly determine the header format in most cases. 

Q queuedir Sdect the directory in which to queue messages. 

r timeout The timeout on reads; if none is set, sendmail will wait forever for a mailer. This option 
violates the word (if not the intent) of theSM TP specification, so theti meout should 
probably be fairly large. 


S file Save statistics in the named file 

s Always instantiate the queue file, even under circumstances where it is not strictly 
necessary. T his provides safety against system crashes during delivery. 

T time Se@ the time-out on undelivered messages in the queue to the specified time. After 


ddivery has failed (for example because of a host being down) for this amount of time 
failed messages will be returned to the sender. T he default is three days. 

tstz, dtz Set the name of thetime zone. 

U userdatabase If set, a user database is consulted to get forwarding information. You can consider this 
an adjunct to the aliasing mechanism, except that the database is intended to be 
distributed; aliases are local to a particular host. This might not be available if your 
sendmail does not have the users option compiled in. 

uN Sé@ the default user 1D for mailers. 

w If not set, name server lookups will use a query type of any to find types cname, a, and mx 
and will cause all existing records to be cached by the local server. If there is (or might 
be) a wildcard ux in the local domain or its parents that are searched, you must set this 
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option, which uses a query type of cname only; otherwise, it causes all fully qualified 
names to match as namesin the local domain. 


In aliases, the first character of aname can bea vertical bar to cause interpretation of the rest of the name as a command to 
pipe the mail to. It might be necessary to quote the name to keep sendmail from suppressing the blanks between arguments. 
For example, a common alias is 


msgs: ";/usr/bin/msgs -s" 

Aliases can also have the syntax to ask sendmail to read the named file for a list of recipients. For example, an alias such as 
poets: ":include:/usr/local/lib/poets.list" 

would read for the list of addresses making up the group. 

sendmail returns an exit status describing what it did. The codes are defined in sysexits.h: 


EX_OK Successful completion on all addresses. 

EX_NOUSER Username not recognized. 

EX_UNAVAILABLE Catchall meaning necessary resources were not available. 
EX_SYNTAX Syntax error in address. 

EX_SOFTWARE Internal software error, including bad arguments. 
EX_OSERR Temporary operating system error, such as cannot fork. 
EX_NOHOST H ostname not recognized. 

EX_TEMPFAIL M essage could not be sent immediately but was queued. 


If invoked aS newaliases, sendmail rebuilds the alias database If invoked aS mailg, sendmail prints the contents of the mail 
queue. If invoked aS smtpd, sendmail forks and runs asa daemon. If invoked aSbsmtp, sendmail processes batched SM TP on 
standard input. If invoked as rung, sendmail runs through the mail queue and makes what dediveries are possible. 


FILES 


Except for the file /etc/sendmail.ct itself, the following pathname are all specified in /etc/sendmail.cf. T hus, these values 
are only approximations. 


/etc/aliases raw data for alias names 
/etc/aliases.pag 

/etc/aliases.dir database of alias nanes 
/etc/sendmail.cf configuration file 
/etc/sendmail.fc frozen configuration 
/etc/sendmail nt hdp file 
/var/log/sendmail.st collected statistics 
/var/spool/mqueue/* temp files 


SEE ALSO 
binmail(1), mail(1), rmail(1), sysiog(3), aliases(5), mailaddr(7), rc(8); DARPA Internet Request for CommentsRFC 819, 
RFC 821, RFC 822; “Sendmail: An Internetwork M ail Router,” SMM and No.16, “Sendmail Installation and O peration 
Guide,” SMM and No.7. 

HISTORY 


The sendmail command appeared in BSD 4.2. 
BSD 4,5 August 1991 
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setfdprm 


setfdprm— Sets user-provided floppy disk parameters. 
SYNOPSIS 


setfdprm 
setfdprm 
setfdprm 
setfdprm 
setfdprm 


DESCRIPTION 


setfdprm is a utility that can be used to load disk parameters into the auto-detecting floppy devices, to clear old parameter 
sets, and to disable or enable diagnostic messages. 


device name 

device size sectors heads tracks stretch gap rate specl fmt_gap 
device 

device 

device 


sx ots 


Without any options, setfdprm loads the device (usually /dev/fao or /dev/fdt) with anew parameter set with the name entry 
found in /etc/fdprm (usually named 360/360 and so on). T hese parameters stay in effect until the media is changed. 





OPTIONS 
-p device name Permanently loads anew parameter set for the specified auto-configuring floppy device 
for the configuration with name in /etc/fdprm. Alternatively, the parameters can be given 
directly from the command line. 
-c device Clears the parameter set of the specified auto-configuring floppy device. 
-y device Enables format detection messages for the specified auto-configuring floppy device. 
-n device Disables format detection messages for the specified auto-configuring floppy device. 
BUGS 
This documentation is grossly incomplete. 
FILES 
/etc/fdprm 
AUTHOR 


Werner Almesberger (almesber@nessie.cs.id.ethz.ch) 
Linux 0.99, 20 N ovenber 1993 


setserial 


setserial— Ge@t/set Linux serial port information. 


SYNOPSIS 


setserial [ -abqvVW ] device [ parameter] [ arg ] ] ... 
setserial -g [ -abv ] devicel ... 


DESCRIPTION 


setserial isaprogram designed to set or report the configuration information associated with a serial port. This information 
includes what !/O port and IRQ aparticular serial port is using, whether the break key should be interpreted as the Secure 
Attention K ey, and so on. 


D uring the normal bootup process, only COM ports 1-4 are initialized, using the default I/O ports and IRQ values, as 
listed. To initialize any additional serial ports, or to change the COM 1-4 ports to anonstandard configuration, the 
setserial program should be used. Typically, it is called from an rc.serial script, which is usually run out of /etc/rc.1ocal. 
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The deviceargument or arguments specify the serial device that should be configured or interrogated. It will usually have the 
following form: /dev/cua[0-3]. 


If no parameters are specified, setserial prints the port type (such as 8250, 16450, 16550, 16550A), thehardware|/O port, 
the hardware IRQ line, its “baud base,” and some of its operational flags. 


If the -g option is given, the arguments to setserial are interpreted as alist of devices for which the characteristics of those 
devices should be printed. 


W ithout the -g option, the first argument to setserial isinterpreted asthe device to be modified or characteristics to be 
printed, and any additional arguments are interpreted as parameters that should be assigned to that serial device. 


For the most part, superuser privilege is required to set the configuration parameters of a serial port. A few serial port 
parameters can be set by normal users, however, and these are noted as exceptions in this manual page. 


OPTIONS 
setserial accepts the following options: 


-a W hen reporting the configuration of a serial device print all available information. 


-b W hen reporting the configuration of a serial device print a summary of the device's 
configuration, which might be suitable for printing during the bootup process during 
the /etc/rc script. 


q Be quid. setserial will print fewer lines of output. 

v Be verbose. setserial will print additional status output. 
-V Display version and exit. 

Ww Do wild interrupt initialization and exit. 


PARAMETERS 
The following parameters can be assigned to a sevial port. 
All argument values are assumed to bein decimal unless preceded by ox. 


port port_number The port option sets thel/O port as described previously. 
irg irg_number The irg option sets the hardware IRQ as described previously. 
uart vart_type This option is used to set the UART type. The permitted types arenone, 8250, 16450, 


16550, and 16550A. Because the 8250 and 16450 UARTs do not have FIFOs, and 
because the original 16550 have bugs that make the FIFOs unusable, the FIFO will only 
be used on chips identified as 16550A UARTs. Setting the UART type to 8250, 16450, 
or 16550 will enable the serial port without trying to use the FIFO. Using the UART 
type nonewill disable the port. Some internal modems are billed as having a “16550A 
UART with a1KB buffer.” Thisis alie They do not really have a 16550A-compatible 
UART; instead, what they haveis a 16450-compatible UART with a 1KB receive buffer 
to prevent receiver overruns. This isimportant because they do not have atransmit 
FIFO. Hence, they are not compatible with a 16550A UART, and the autocon- 
figuration process will correctly identify them as 16450s. If you attempt to override this 
using the uart parameter, you see dropped characters during file transmissions. T hese 
UARTs usually have other problems: The skip test parameter also often must be 
specified. 

autoconfig W hen this parameter is given, setserial asks thekernd to attempt to automatically 
configure the serial port. Thel/O port must be correctly set; the kernel will attenpt to 
determine the UART type, and if the auto_irq parameter is set, Linux will attempt to 
automatically determine the IRQ. T he autoconfigure parameter should be given after 
the port, auto_irg, and skip test parameters have been specified. 


auto_irq 


“auto_irg 


skip_test 


“skip_test 
baud_base baud_base 


spd_hi 


spd_vhi 


spd_cust 


spd_normal 


divisor divisor 


“sak 

fourport 
“fourport 
close_delay delay 


Session_lockout 


“session_lockout 


pgrp_lockout 


“pgrp_lockout 
hup_notify 


“hup_notify 


setserial 


D uring autoconfiguration, try to determine the IRQ. This feature is not guaranteed to 
always produce the correct result; some hardware configurations will fool the Linux 
kernd. It is generally safer not to use the auto_irq feature but rather to specify the IRQ 
to be used explicitly, using the irq parameter. 

D uring autoconfiguration, do not try to determinetheIRQ. 

D uring autoconfiguration, skip the UART test. Some internal modems do not have 

N ational Semiconductor compatible UART s but have cheap imitations instead. Some of 
these cheesy imitation UART sdo not fully support the loopback detection mode, which 
is used by the kernel to make sure there really isa UART at aparticular address before 
attempting to configure it. For certain internal modems, you will need to specify this 
parameter so Linux can initializethe UART correctly. 

D uring autoconfiguration, do not skip the UART test. 

This option sets the base baud rate, which is the clock frequency divided by 16. Usually, 
this value is 115200, which is also the fastest baud rate which the U ART can support. 
Use57.6KB when the application requests 38.4K B. This parameter can be specified by 
anon-privileged user. 
Use 115KB when the application requests 38.4K B. T his parameter can be specified by a 
non-privileged user. 

Use the custom divisor to set thespeed when the application requests 38.4K B. In this 
case, the baud rate is the baud_base divided by the divisor. T his parameter can be 
specified by anon-privileged user. 

Use 38.4KB when the application requests 38.4K B. This parameter can be specified by 
anon-privileged user. 

This option sets the custom divisor. T his divisor will be used when the spd_cust option 
is selected and the serial port is set to 38.4KB by the application. This parameter can be 
specified by anon-privileged user. 

Se the break key at the Secure Attention K ey. 

Disable the Secure Attention K ey. 

Configure the port as an AST Fourport card. 

Disable AST Fourport configuration. 

Specify the amount of time in hundredths of asecond, that DTR should remain low on 
a serial line after the callout deviceis closed before the blocked dial-in device raises DTR 
again. T he default value of this option is5o, or a half-second delay. 

Lock out callout port (/dev/cuaxx) accesses across different sessions. T hat is, oncea 
process has opened a port, do not allow a process with a different session ID to open 
that port until the first process has closed it. 

Do not lock out callout port accesses across different sessions. 

Lock out callout port (/dev/cuaxx) accesses across different process groups. T hat is, once 
a process has opened a port, do not allow a process in a different process group to open 
that port until the first process has closed it. 

Do not lock out callout port accesses across different process groups. 

N otify a process blocked on opening a dial-in line when a process has finished using a 
callout line (either by closing it or by the sevial line bang hung up) by returning EAGAIN 
to the open. 

The application of this parameter is for gettys that are blocked on a sevial port's dial-in 
line This allows the getty to reset the moden (which may have had its configuration 
modified by the application using the callout device) before blocking on the open again. 
Do not notify a process blocked on opening a dial-in line when the callout device is 
hung up. 
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split_termios Treat the termios settings used by the callout device and the termios settings used by the 
dial-in devices as separate. 

“split_termios Use the sametermios structure to store both the dial-in and callout ports. This isthe 
default option. 

callout_nohup If this particular serial port is opened as a callout device, do not hang up the tty when 
carrier detect is dropped. 

“callout_nohup Do not skip hanging up the tty when a serial port is opened as a callout device Of 


course, the HupcL termios flag must be enabled if the hangup is to occur. 


CONSIDERATIONS OF CONFIGURING SERIAL PORTS 


It is important to note that setserial merely tells the Linux kernd where it should expect to find the!/O port and IRQ lines 
of a particular serial port. It does not configure the hardware, the actual serial board, to use a particular I/O port. To do that, 
you need to physically program the serial board, usually by setting some jumpers or by switching some DIP switches. 


This section provides some pointers in hdping you decide how you want to configure your serial ports. 
The “standard MS-DOS" port associations are 


/dev/ttyse (COM 1), port Ox3f8 IRQ 4 
/dev/ttys1 (COM 2), port Ox2f8 IRQ 3 
/dev/ttys2 (COM 3), port 0x3e8 IRQ 4 
/dev/ttys3 (COM 4), port 0x2e8 IRQ 3 


D ueto the limitations in the design of theAT/ISA bus architecture, an IRQ line usually cannot be shared between two or 
more sevial ports. If you attempt to do this, one or both serial ports will become unrdiable if you try to use both smulta- 
neously. This limitation can be overcome by special multiport serial port boards, which are designed to share multiple serial 
ports over asingle|RQ line M ultiport serial cards supported by Linux include the AST FourPort, the Accent Async board, 
the Usenet Serial || board, the Bocaboard BB-1004, BB-1008, and BB-2016 boards, and the H UB-6 serial board. 


Theselection of an alternative|RQ lineis difficult because most of them are already used. T he following table lists the 
“standard MS-DOS” assignments of available |RQ lines: 


IRQ 3 COM2 
IRQ 4 COM1 
IRQ 5 LPT 2 
IRQ 7 LPT1 


M ost people find that IRQ 5 isagood choice assuming that there is only one paralld port active in the computer. Another 
good choiceisIRQ 2 (a.k.a. IRQ 9), although thisIRQ is sometimes used by network cards, and very rardy will VGA cards 
be configured to useIRQ 2 asavetical retraceinterrupt. If your VGA card is configured this way, try to disable it so you 
can reclaim that IRQ line for some other card. It’s not necessary for Linux and most other operating systans. 


Theonly other available|RQ lines are 3, 4, and 7, and these are probably used by the other serial and parallel ports. (If your 
serial card has a 16-bit card edge connector and supports higher interrupt numbers, then IRQ 10, 11, 12, and 15 are also 
available.) 


On AT classmachines, IRQ 2 issen asIRQ 9, and Linux will interpret it in this manner. 


IRQ sother than 2 (9), 3, 4, 5, 7, 10, 11, 12, and 15 should not be used because they are assigned to other hardware and 
cannot, in general, be changed. H ere are the “standard” assignments: 


IRQ 0 Timer channel 0 

IRQ 1 K eyboard 

IRQ 2 Cascade for controller 2 
IRQ 3 Seial port 2 


IRQ 4 Sevial port 1 


sid 


IRQ 5 Parallel port 2 (Reserved in PS/2) 
IRQ 6 Floppy diskette 
IRQ 7 Parallel port 1 
IRQ 8 Real-time clock 
IRQ 9 Redirected to IRQ2 
IRQ 10 Reserved 
IRQ 11 Reserved 
IRQ 12 Reserved (Auxiliary device in PS/2) 
IRQ 13 M ath coprocessor 
IRQ 14 H ard disk controller 
IRQ 15 Reserved 

CAUTION 

Using an invalid port can lock up your machine. 


FILES 
/etc/rc.local 
/etc/rc.serial 


SEE ALSO 


tty(4), ttys(4), kernel/chr_drv/serial.c 


AUTHOR 


The original version of setserial was written by Rick Sladkey (jrs@world.std.com) and was modified by M ichad K. Johnson 
(johnsonm@stolaf.edu). 


This version has since bee rewritten from scratch by TheodoreT s/o (tytso@mit.edu) on 1/1/93. Any bugs or problems are 
soldy his responsibility. 


serial 2.10, 27 August 1994 


setsid 


setsid— Run a program in anew session. 


SYNOPSIS 


setsid program [ arg ... ] 


DESCRIPTION 


setsid runs a program in anew session. 


SEE ALSO 


setsid(2) 
AUTHOR 
Rick Sladkey (jrs@world.std.com) 
Linux 0.99, 20 N ovanber 1993 
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Showmount 


showmount— Show mount information for an N FS server. 


SYNOPSIS 


/usr/etc/showmount [\-adehv\][\--all\][\--directories\] 
[\--exports\][\--help\] [\--version\][\host \] 


DESCRIPTION 
showmount queries the mount daemon on a remote host for information about the state of the N FS server on that machine. 
With no options, showmount lists the set of clients who are mounting from that host. T he output from showmount is designed 
to appear as though it were processed through sort -u. 


OPTIONS 
-a OF --all List both the client hostname and mounted directory in host :dir format. 
-d Or --directories List only the directories mounted by some client. 
-e OF --exports Show the N FS server's export list. 
-h OF - -help Provide a short hdp summary. 
-v OF --version Report the current version number of the program. 
--no-headers Suppress the descriptive headings from the output. 
SEE ALSO 
rpc.mountd(8), rpc.nfsa(8) 
BUGS 


The completeness and accuracy of the information that showmount displays varies according to the N FS server's implementa- 
tion. Because showmount sorts and uniques the output, it is impossibleto determine from the output whether a client is 
mounting the same directory more than once 


AUTHOR 


Rick Sladkey (jrs@world.std.com) 
6 October 1993 


shutdown 


shutdown— Close down the system. 


SYNOPSIS 
shutdown [ -h | -r ] [ -fgs ] [ now {| hh:ss | +mins ] 
reboot [ -h | -r ] [ -fqs ] [ now {| hh:ss | +mins ] 
fastboot [ -h | -r ] [ -fqs ] [ now} hh:ss {| +mins ] 
halt [ -h | -r ] [ -fqs ] [ now | hhiss | +mins ] 
fasthalt [ -h | -r ] [ -fqs ] [ now | hh:ss {| +mins ] 
DESCRIPTION 


In general, shutdown prepares the system for a power down or reboot. An absolute or data time can be given, and periodic 
messages will be sent to all users warning of the shutdown. 


halt isthe same as shutdown -h -q now. 


fasthalt isthe same as shutdown -h -q -f now. 


gmplanit 1397 


reboot isthe same aS shutdown -r -q now. 
fastboot isthe same as shutdown -r -q -f now. 
The default data time if noneis specified, is two minutes. 


Five minutes before shutdown (or immediately, if shutdown is less than five minutes away), the /etc/nologin file is created 
with a message stating that the system is going down and that logins areno longer permitted. The 1ogin(1) program will not 
allow non-superusers to log in during this period. A message will be sent to all users at this time 


W hen the shutdown time arrives, shutdown notifies all users, tals init(8) not to spawn more getty(8)s, writes the shutdown 
time into the /var/1og/wtmp file, kills all other processes on the system, sync(2)s, unmounts all the disks, sync(2)s again, waits 
for a second, and then ether terminates or reboots the system. 


OPTIONS 
-h H alt the system. D o not reboot. This option is used when powering down the systen. 
-r Reboot the systen. 
-f Fast. W hen the system is rebooted, the filesystems will not be checked. T his is arranged 
by creating /fastboot, which /etc/rc must detect (and ddete). 
-q Quiet. This uses a default broadcast message and does not prompt the user for one. 
-s Reboot in single user mode Thisis arranged by creating /etc/singleboot, which 
simpleinit(8) detects (and dedetes). 
FILES 
/etc/rc 
/fastboot 
/etc/singleboot 
/etc/nologin 
/var/log/wtmp 
SEE ALSO 
umount(8), login(1), reboot(2), simpleinit(8), init(8) 
BUGS 


UnliketheBSD shutdown, users are notified of shutdown only once or twice, instead of many time, and at shorter and 
shorter intervals as “apocalypse approaches.” 


AUTHOR 


poe@daimi.aau.dk. M odified by jrse@world.std.com. 
Linux 0.99, 20 N ovenber 1993 


simpleinit 
simpleinit— Process control initialization. 


SYNOPSIS 


init [ single ] 
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DESCRIPTION 


init iSinvoKed as the last step in the Linux boot sequence If the single option is used, or if the file /etc/singleboot exists, 
then single user mode will be entered, by starting /bin/sh. If thefile /etc/securesingle exists, then the root password will be 
required to start single-user mode. If the root password does not exist, or if /etc/passwd does not exist, the checking of the 
password will be skipped. 


If the file /etc/tz exists, then the contents of that file will be read and used to set the tz environment variable for each 
process started by simpleinit. This “feature” is only available if it’s configured at compile time. It’s not usually needed. 


After single-user mode is terminated, the /etc/rc file is executed, and theinformation in /etc/inittab will be used to start 
processes. 


W hile init is running, several signals are trapped with special action taken. Because init hasPID 1, sending signals to the 
init process is easy with the ki11(1) command. 


If init catches a stcHup (hangup) signal, the /etc/inittab will be read again. If init catches a statstp (terminal stop) signal, 
no more processes will be spawned. T hisis a toggle, which is reset if init catches another siatstP signal. 


If init catches a starnt (interrupt) signal, init will sync a few times and try to start reboot. Failing this, init will execute the 
system reboot(2) call. Under Linux, it is possible to configure the C tri+Alt+D d sequence to send a signal to init instead of 
rebooting the system. 


THE inittab FILE 


Because of the number of init programs that are appearing in the Linux community, the documentation for the 
/etc/inittab file, which is usually found with the inittab(5) man page, is presented here: 


The format is 
ttyline:termcap-entry: getty - command 
An example follows: 


tty1:console:/sbin/getty 9600 tty1 
tty2:console: /sbin/getty 9600 tty2 
tty3:console: /sbin/getty 9600 tty3 
tty4:console: /sbin/getty 9600 tty4 

# tty5:console:/sbin/getty 9600 tty5 

# ttyS1:dumb:/sbin/getty 9600 ttyS1 

# ttyS2:dumb:/sbin/getty -m -t60 2400 ttyS2 


Lines beginning with the # character are treated as comments. Please see documentation for the getty(8) command that you 
are using because there are several of these in the Linux community at this time 


FILES 
/etc/inittab 
/etc/singleboot 
/etc/securesingle 
/etc/TZ 
/etc/passwd 


/etc/rc 


SEE ALSO 


inittab(5), ctrlaltdel(8) reboot(8), termcap(5), getty(8), agetty(8), shutdown(8) 


gi plogin 
BUGS 


This program is called simpleinit to distinguish it from the System V compatible versions of init that are starting to appear 
in the Linux community. simpleinit should be linked to, or made identical with, init for correct functionality. 


AUTHOR 
Peter O rbaek (poe@daimi.aau.dk), version 1.20, with patches for single-user mode by W erner Almesberger. 
Linux 0.99, 20 N ovanber 1993 


Slattach 


slattach— Attach a network interface to a serial line. 


SYNOPSIS 


slattach [-v] [-p proto] [-s speed] [tty] 


DESCRIPTION 


slattach iS a little program that can be used to put anormal terminal (“serial”) line into one of several “network” modes, 
thus allowing you to use it for point-to-point links to other computers. 


OPTIONS 
[-v] Enable debugging output. U seful when determining why a given setup doesn’t work. 
[-p proto] Set a specific kind of protocol to use on theline. T he default is set to cslip, compressed 


SLIP. O ther possible values are slip (normal SLIP), ppp (Point-to-Point Protocol), and 
kiss (AX.25 TNC protocol). 


[-s speed] Se a specific line speed other than the default. 


If no arguments are given, the current terminal line (usually the login device) is used. 
O therwise, an attempt is made to claim theindicated terminal port, lock it, and open it. 


FILES 


/dev/cua* 


BUGS 


N one so far. 


AUTHOR 


Fred N. van Kempen (waltje@uwalt.n1.mugnet.org) 
20 September 1993 


Sliplogin 
sliplogin— Attach a serial line network interface 


SYNOPSIS 


sliplogin [| ogi nname ] 


DESCRIPTION 


sliplogin is used to turn the terminal line on standard input into aserial lineIP SLIP link to aremote host. To do this, the 
program searches the file for an entry matching! ogi nname (which defaults to the current login name if omitted). If a 
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matching entry is found, the line is configured appropriately for slip (8-bit transparent I/O ) and converted to slip line 
discipline Then ashal script is invoked to initialize the slip interface with the appropriate local and remote | P address, 
netmask, and so on. 


The usual initialization script is /etc/slip/slip.1gin, but if particular hosts need special initialization, the file 
/etc/slip/slip. login. 1loginname will be executed instead if it exists. The script is invoked with the parameters 


slipunit The unit number of the slip interface assigned to this line, such aso for slo. 
speed The speed of the line. 
args The arguments from the entry, in order starting with | ogi nname. 


Only the superuser can attach a network interface. T he interface is automatically detached when the other end hangs up or 
the sliplogin process dies. If the kernd slip module has been configured for it, all routes through that interface will also 
disappear at the same time. If thereis other processing asite wants done upon hangup, the file /etc/slip/slip.logout or 
/etc/slip/slip.1logout.1loginname is executed if it exists. It isgiven the same arguments as the login script. 


FORMAT OF /etc/slip. hosts 


Comments (lines starting with a #) and blank lines are ignored. O ther lines must start with al ogi nname, but the remaining 
arguments can be whatever is appropriate for the file that will be executed for that nane. Arguments are separated by 
whitespace and follow normal sh(1) quoting conventions (howeve,, | ogi nname Cannot be quoted). U sually, lineshave the 
form |oginname |ocal-address remote-address netmask opt-args.local-address andremote-address arethelP hostnames or 
addresses of the local and remote ends of theslip line and net mask isthe appropriate|P netmask. These arguments are passed 
directly to ifconfig(8). opt-args areoptional arguments used to configure the line 


EXAMPLE 


Thenormal use of sliplogin is to create a entry for each legal, remote slip site with sliplogin as the shell for that entry, 
such as 


Sfoo:ikhuy6:2010:1:slip line to foo:/tmp:/usr/sbin/sliplogin. 

(O ur convention isto name the account used by remote host hostname as shostname.) Then an entry is added that looks like 
Sfoo ‘hostname ' foo netmask 

‘hostname’ will be evaluated by sh to thelocal hostname and net mask isthelocal host IP netmask. 


N ote that s1iplogin must be setuid to root, and although it’s not a security hole moral defectives can use it to place terminal 
linesin an unusable state or deny access to legitimate users of aremoteslip line. To prevent this, a site can create a group, say 
slip, that only the slip login accounts are put in and then make sure that /sbin/sliplogin iSin group slip and mode 4550 
(setuid root, only group slip can execute binary). 


DIAGNOSTICS 


sliplogin logs various information to the system log daanon, sysloga(8), with a facility code of daemon. T he messages are 
listed here, grouped by severity level. 


Error Severity 





ioctl (TCGETS): reason A TCGETS ioct1 to g@ the line parameters failed. 
ioctl (TCSETS): reason A TCSETS ioctl to set the line parameters failed. 
/etc/slip.hosts: reason The file could not be opened. 

access denied for user No entry for user was found in /etc/slip/slip.hosts 


N otice Severity 





"attaching slip unit" unit for Unit was successfully attached. 
loginname SLIP unit 


oe ze 


SEE ALSO 


slattach(8), syslogd(8) 


HISTORY 
The sliplogin command is currently in beta test. 
5 August 1991 


Swapon, swapotf 


swapon, swapoff— Enable/disable devices and files for paging and swapping. 


SYNOPSIS 


/sbin/swapon -a 

/sbin/swapon specialfile ... 
/sbin/swapoff -a 
/sbin/swapoff specialfile ... 


DESCRIPTION 


swapon is used to specify devices on which paging and swapping are to take place Calls to swapon usually occur in the system 
multiuser initialization file /etc/rc making all swap devices available, so that the paging and swapping activity is interleaved 
across several devices and files. 


Usually, the first form is used: 
-a All devices marked as sw swap devices in /etc/fstab are made available 


swapoff disables swapping on the specified devices and files or on all swap entriesin /etc/fstab when the -a flag is given. 


SEE ALSO 
swapon(2), swapoff(2), fstab(5), init(8), mkswap(8), rc(8), mount(8) 
FILES 
/dev/hd[ ab]? Standard paging devices 
/dev/sd[ab]? Standard (SCSI) paging devices 
/etc/fstab ASCII filesystem description table 
HISTORY 
The swapon command appeared in 4.0 BSD. 
AUTHORS 


See the Linux mount(8) man page for a complete author list. Primary contributors include D oug Q uale, HJ. Lu, Rick 
Sladkey, and Steohen T weedie. 


Linux 0.99, 27 N ovember 1993 


sync 


sync— Flush Linux filesystem buffers. 
SYNOPSIS 


sync 
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DESCRIPTION 


syne executes sync(2), which flushes the filesystem buffers to disk. sync should be called before the processor is halted in an 
unusual manner (before causing a kernd panic when debugging new kernel code). In general, the processor should be halted 
using the reboot(8) or halt(8) commands, which attempt to put the systen in a quiescent state before calling sync(2). 


From Linus: “N ote that sync is only guaranteed to schedule the dirty blocks for writing: It can actually take a short time 
before all the blocks are finally written. If you are doing the sync with the expectation of killing the machine soon after, 
please take this into account and sleep for a few seconds. (T he reboot(8) command takes these precautions.)” 


SEE ALSO 


sync(2), update(8), reboot(8), halt(8) 
AUTHOR 
LinusT orvalds (torvalds@cs. helsinki. fi) 
Linux 0.99, 20 N ovember 1993 


sysklogd 
sysklogd— Linux systen logging utilities. 
DESCRIPTION 


sysklogd provides two system utilities, which provide support for system logging and kernd message trapping. Support of 
both inetd and UNIX domain sockets enables this utility package to support both local and renote logging. 


System logging is provided by aversion of syslogd derived from the stock BSD sources. Support for kernd logging is 
provided by the klogd utility, which allows kernel logging to be conducted in either a stand-alone fashion or asa client of 
syslogd. 





Although the syslogd sources have been heavily modified, a couple of notes are in order. First of all, there has been a 
systematic attempt to ensure that syslogd follows standard BSD behavior as its default. The second important concept to 
note is that this version of syslogd interacts transparently with the version of syslog found in the standard libraries. If a 
binary linked to the standard shared libraries fails to function correctly, we want an example of the anomalous behavior. 


CONFIGURATION FILE SYNTAX DIFFERENCES 
syslogd uses a Slightly different syntax for its configuration file from that of the original BSD sources. O riginally, all messages 
of a specific priority and above were forwarded to the log file 
For example, the following line caused all output from the daemon facilities to go into /usr/adm/daemons: 
# Sample syslog.conf 
daemon.debug /usr/adm/daemons 
Under the new schene, this behavior renains the same. T he difference is the addition of two new wildcard specifiers: 
the asterisk (*) and the equals sign (=). The * specifies that all messages for the indicated facility are to be directed to the 
destination. N ote that this behavior is degenerate with specifying a priority level of debug. Users have indicated that the 
asterisk notation is more intuitive. 
The = wildcard is used to restrict logging to the specified priority class. This allows, for example, routing only debug messages 
to a particular logging source. 
For example, the following line in syslog.conf directs debug messages from all sources to the /usr/adm/debug file 


# Sample syslog.conf 
daemon.=debug /usr/adm/debug 


gyklogd 


This may take some acclimatization for those individuals used to the pure BSD behavior, but testers have indicated that this 
syntax is somewhat more flexible than the BSD behavior. N ote that these changes should not affect standard syslog.conf 
files. You must specifically modify the configuration files to obtain the enhanced behavior. 


SU PPO RT FOR REMOTE LOGGING 


These modifications provide network support to the syslogd facility. N etwork support means that messages can be forwarded 
from onenoderunning syslogd to another noderunning syslogd where they will be actually logged to a dix file. 


The strategy isto have syslogd listen on aUNIX domain socket for locally generated log messages. T his behavior will allow 
syslogd to interoperate with the syslog found in the standard C library. At the same time syslogd listens on the standard 
syslog port for messages forwarded from othe hosts. To havethis work correctly, the services files (typically found in 
/usr/etc/inet) must havethe following entry: 





syslog 514/udp 


To cause messages to be forwarded to another host, replace the normal file line in the sysiog.conf file with the name of the 
host to which the messages is to be sent prepended with an @. 


For example, to forward all messages to a renote host, use the following syslog.conf entry: 


# Sample syslogd configuration file to 
# messages to a remote host forward all. 
-* @hostname 


To forward all kernd messages to a remote host, the configuration fileis 


# Sample configuration file to forward all kernel 
# messages to a remote host. 
kern.* @hostname 


OUTPUT TO NAMED PIPES (FIFO S) 


This version of syslogd has support for logging output to named pipes (FIFOs). A FIFO or named pipe can be used as a 
destination for log messages by prepending a| to the name of the file This is handy for debugging. N ote that the FIFO must 
be created with the mkfifo command before syslogd is started. 

The following configuration file routes deoug messages from the kernel to aFIFO: 

# Sample configuration to route kernel debugging 

# messages ONLY to /usr/adm/debug which is a 


# named pipe. 
kern.=debug | /usr/adm/debug 


INSTALLATION CONCERNS 


There is probably oneimportant consideration when installing this version of syslogd. T his version of syslogd is dependent 
on proper formatting of messages by the sysiog function. T he functioning of the syslog function in the shared libraries 
changed somewhere in the region of 1ibc.so.4.[2-4].n. The specific change was to null-terminate the message before 
transmitting it to the /dev/10g socket. Proper functioning of this version of syslogd is dependent on null-termination of the 
message. 


This problen will typically manifest itself if old statically linked binaries are being used on the system. Binaries using old 
versions of the syslog function will cause enpty lines to be logged, followed by the message with the first character in the 
message removed. R elinking these binaries to newer versions of the shared libraries will correct this problem. 


SECURITY THREATS 


There is the potential for the syslogd daanon to be used as a conduit for a denial of service attack. Thanks go to J ohn 
Morrison (jmorriso@rflab.ee.ubc.ca) for alerting me to this potential. A rogue programme’ could very easily flood the 
syslogd daenon with syslog messages resulting in the log files consuming all the remaining space on the filesystem. 
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Activating logging over the inet domain sockets will of course expose a system to risks outside of programs or individuals on 
the local machine. 


Version 1.2 of the utility set will address this problem. In the meantime, there are a number of methods for protecting a 
machine: 


1. Logging can be directed to an isolated or non-root filesysten, which, if filled, will not impair the machine 

2. The ext2 filesystem can be used, which can be configured to limit a certain percentage of a filesystem to usage by root 

only. N ote that this will require syslogd to be run as anon-root process. Also note that this will prevent usage of remote 

logging because syslogd will be unable to bind to the 514/U D P socket. 

Disabling inet domain sockets will limit risk to the local machine. 

4. UseStep 3 and if the problem persists and is not secondary to a rogue program or daemon, get a 3.5 foot (approximated y 
1 mete) length of sucker rod and have a chat with the user in question. A sucker rod is 3/4-, 7/8-, or 1-inch hardened 
steel rod, male threaded on each end. Its primary usein the oil industry in W estern N orth D akota and othe’ locationsis 
to pump-suck oil from oil wells. Secondary uses are for the construction of cattle feed lots and for dealing with the 
occasional recalcitrant or belligerent individual. 


FILES 


/etc/syslog.conf 


BUGS 


Primarily, security concerns will be addressed in version 1.2. 


SEE ALSO 


klogd(1) 


COLLABORATORS 


Dr. Greg W ettstein (gregswind. uucp@plains.nodak.edu) 
Enjellic Systems D evdopment 

Oncology Research Division Computing Facility 
Roger M aris Cancer C enter 

Fargo, ND 

Stephen T weedie 

Department of C omputer Science 

Edinburgh University, Scotland 

Juha Virtanen 

(jiivee@hut.fi) 

Shane Alderton 


(shane@scs.apana.org.au) 
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syslogd 


syslogd— Log systems messages. 


SYNOPSIS 
syslogd [-f config file] [-m mark_interval ] [-p log_socket ] 
DESCRIPTION 


syslogd reads and logs messages to the system console, log files, and other machines or users as specified by its configuration 
file. The options are as follows: 


talkd 


-f Specify the pathname of an alternate configuration file the default is /etc/syslog.conf. 
-m Sdect the number of minutes between “mark” messages; the default is 20 minutes. 
-p Specify the pathname of an alternate log socket; the default is /dev/1og. 


syslogd reads its configuration file when it starts up and whenever it receives a hangup signal. For information on the format 
of the configuration file, see syslog.conf(5). 


syslogd reads messages from the UN 1X domain socket /dev/1og, from an Internet domain socket specified in /etc/services, 
and from the special device /dev/klog (to read kernel messages). 


syslogd creates the file /var/run/syslog.pid and stores its processID there. T hiscan be used to kill or reconfigure syslogd. 


The message sent to syslogd should consist of asingle line. T he message can contain a priority code, which should bea 
preceding decimal number in angle braces, such as<5>. This priority code should map into the priorities defined in the 
include file <sys/syslog.h>. 


FILES 
/etc/syslog. conf The configuration file 
/var/run/syslog.pid The process!D of current syslogd 
/dev/log N ameof the UNIX domain datagram log socket 
/dev/klog Thekernel log device 
SEE ALSO 
logger(1), syslog(3), services(5), syslog. conf(5) 
HISTORY 


The syslogd command appeared in BSD 4.3. 
BSD 4.2, 16 March 1991 


talkd 


talkd— Remote user communication server. 


SYNOPSIS 


talkd 


DESCRIPTION 


talkd isthe server that notifies a user that someone dse wants to initiate a conversation. It acts a repository of invitations, 
responding to requests by clients who want to rendezvous to hold a conversation. In normal operation, a client, the caller, 
initiates a rendezvous by sending actL mse to the server of type Look uP (Se protocols/talkd.h). T his causes the server to 
search its invitation tables to check if an invitation currently exists for the caller (to speak to the callee specified in the 
message). If the lookup fails, the caller then sends an ANNOUNCE message, causing the server to broadcast an announcement on 
the callee’s login ports requesting contact. W hen the callee responds, the local server uses the recorded invitation to respond 
with the appropriate rendezvous address and the caller and callee client programs establish a stream connection through 
which the conversation takes place 


SEE ALSO 


talk(1), write(1) 
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HISTORY 
The talkd command appeared in BSD 4.3. 


BSD 4.3, 16 March 1991 


telnetd 


telnetd— DARPA Telnet protocol server. 


SYNOPSIS 


/etc/telnetd [-debug [port ]] [-1][-D options ][-D report ] 
[-D exercise][-D netdata] [-D ptydata] 


DESCRIPTION 


telnetd isaserver that supports the D ARPA standard T ene virtual terminal protocol. te1neta isinvoked by the Internet 
server (See ineta(8)), usually for requests to connect to the Telnet port as indicated by the /etc/services file (see 
services(5)). If desired the -debug can be used, to start up telnetd Manually, instead of through ineta(8). If started up this 
way, port may be specified to run telnetd on an alternate TCP port numbe. 


The -p option can be used for debugging purposes. T his allows T elnet to print debugging information to the connection, 
allowing the user to see what te1neta is doing. T here are several modifiers: opti ons printsinformation about the negotiation 
of Telnet options, report prints the options information, plus some additional information about what processing is going 
On, net data displays the data stream received by telnetd, ptydata displays data written to the pty, and exercise has not been 
implemented yet. 


telnetd operates by allocating a pseudo-terminal device (see pty(4)) for aclient) and then creating a login process that has the 
slave side of the pseudo-terminal as stdin, stdout, and stderr. telnetd manipulates the master side of the pseudo-terminal, 
implementing the T elnet protocol and passing characters between the renote client and thelogin process. 


When aT elnet session is started, telnetd sendsT elnet options to the client side, indicating a willingness to do a remote echo 
of characters, to suppress gO ahead, to do remote flow control, and to receive terminal type information, terminal speed 
information, and window size information from the remote client. If the remote client is willing, the renote terminal type is 
propagated in the environment of the created login process. The pseudo-terminal allocated to the client is configured to 
operate in cooked mode and with xtass and crmop enabled (see tty(4)). 


telnetd is willing to do echo, binary, suppress gO ahead, and timing mark. telnetd is willing to have the remote client 
do linemode, binary, terminal type, terminal speed, window size, toggle flow control, environment, X display location, and 
suppress QO ahead. 


If the file /etc/issue.net is present, telnetd will show its contents before the login prompt of aT elnet session (see 
issue.net(5)). 


SEE ALSO 


telnet(1), issue.net(5) 


BUGS 
SomeT elnet commands are only partially implemented. 


Because of bugsin the original 4.2 BSD te1net(1), telneta performs some dubious protocol exchanges to try to discover if 
the remote client is, in fact, a4.2 BSD teinet(1). 


Binary mode has no common interpretation except between similar operating systems (UNIX, in this case). 


Theterminal type name received from the remote client is converted to lowercase. telnetd never sendsT elnet go ahead 
commands. 


20 April 1991 


tftpd 
tftpd— D ARPA Trivial File T ransfer Protocol server. 


SYNOPSIS 


tftpd [directory ...] 


DESCRIPTION 


tftpd isa server that supports the D ARPA Trivial File Transfer Protocol. T he T FT P server operates at the port indicated in 
the tftp service description; see services(5). T he server is usually started by ineta(8). 


The use of tftp(1) does not require an account or password on the remote systen. D ue to the lack of authentication 
information, tftpd will allow only publicly readable files to be accessed. Files may be written only if they already exist and are 
publicly writable N ote that this extends the concept of public to include all userson all hosts that can be reached through 
the network; this may not be appropriate on all systems, and its implications should be considered before enabling the tftp 
service. The server should have the user 1D with the lowest possible privilege. 


SEE ALSO 


tftp(1), ineta(8) 


HISTORY 
Thetftpd command appeared in BSD 4.2. 
BSD 4.2, 13 May1991 


timed 

timed— Time server daemon. 
SYNOPSIS 

timed [-M] [-t] [-d] [-i network] [-n network] [-F host1 host2 ...] 
DESCRIPTION 


timed isatime server daemon and is usually invoked at boot time from the rc(8) file It synchronizes the host's time with the 
time of other machines in alocal area network running timea(8). T hese time servers will slow down the clocks of some 
machines and speed up the clocks of others to bring them to the average network time. The average network timeis 
computed from measurements of clock differences using the!C M P timestamp request message. 


The service provided by timed is based on a master-slave scheme W hen timea(8) is started on amachine it asks the master 
for the network time and sets the host’s clock to that time After that, it accepts synchronization messages periodically sent by 
the master and calls adjtime(2) to perform the neaded corrections on the host’s clock. 


It also communicates with date(1) to set the date globally and with timedc(8), a timed control program. If the machine 
running the master crashes, then the slaves elect a new master from among slaves running with the -u flag. A timed running 
without the -m or -F flags remains a slave The -t flag enables timed to trace the messages it receives in the file 
/var/log/timed.log. T racing can beturned on or off by the program timedc(8). T he -d flag is for debugging the daemon. 

It causes the program to not put itself into the background. U sually, timea checks for a master time server on each network 
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to which it is connected, except as modified by the options. It requests synchronization service from the first master server 
located. If permitted by the -m flag, it provides synchronization service on any attached networks on which no current master 
server is detected. Such a server propagates the time computed by the top-levad master. T he -n flag, followed by the name of 
a network that the host is connected to (see networks(5)), overrides the default choice of the network addresses made by the 
program. Each timethe -n flag appears, that network nameis added to a list of valid networks. All other networks are 
ignored. The -i flag, followed by the name of a network to which the host is connected (see networks(5)), overrides the 
default choice of the network addresses made by the program. Each time the -i flag appears, that network nameis added to a 
list of networks to ignore. All other networks are used by the time daemon. The -n and -i flags are meaningless if used 
together. 


timed checks for a master time server on each network to which it is connected, except as modified by the -n and -i options. 
If it finds masters on more than one network, it chooses one network on which to bea “slave” and then periodically checks 
the other networks to see if the masters there have disappeared. 


One way to synchronize a group of machines is to useaan NTP daemon to synchronize the clock of one machine to a distant 
standard or a radio receiver and -F hostname to tell its timed daemon to trust only itsdf. 


M essages printed by the kernel on the system console occur with interrupts disabled. This means that the clock stops while 
they are printing. A machine with many disk or network hardware problems and consequent messages cannot keep good 
time by itself. Each message typically causes the clock to losea dozen milliseconds. A time daemon can correct the result. 


M essages in the system log about machines that failed to respond usually indicate machines that crashed or were turned off. 
Complaints about machines that failed to respond to initial time settings are often associated with “multi-homed” machines 
that looked for time masters on more than one network and eventually chose to becomea slave on the other network. 


WARNING 


If two or more time daanons, whether timed, NTP, try to adjust the same clock, temporal chaos will result. If both this and 
another time daemon arerun on the same machine, ensure that the -F flag is used, so that timed never attempts to adjust the 
local clock. 


The protocol is based on UD P/IP broadcasts. All machines within the range of a broadcast that are using theT SP protocol 
must cooperate. There cannot be more than a single administrative domain using the -F flag among all machines reached by 
a broadcast packet. Failure to follow this rule is usually indicated by complaints concerning “untrusted” machines in the 
system log. 


FILES 
/var/1og/timed.1og tracing file for timed 
/var/log/timed.masterlog log file for master timed 


SEE ALSO 


date(1), adjtime(2), gettimeofday(2), icmp(4), timedc(8), “TSP: The Time Synchronization Protocol for UNIX 4.3 BSD,” 
R. Gusella, S. Zatti. 


HISTORY 
The timed daemon appeared in BSD 4.3. 
BSD 4.3, 11 May 1993 


timedc 


timedc— Timed control program. 


SYNOPSIS 


timedc [command] [argument ...] 


DESCRIPTION 


traceroute 


timedc is used to control the operation of the timed(8) program. It may be used to 


M easure the differences between machines’ clocks 

Find the location where the master time server isrunning 
Enable or disable tracing of messages reca ved by timed 
Perform various debugging actions 


W ithout any arguments, timede will prompt for commands from the standard input. If arguments are supplied, timedc 
interprets the first argument as a command and the renaining arguments as parameters to the command. The standard input 
may be redirected, causing timedc to read commands from afile Commands may be abbreviated; recognized commands are 


2? [command ...] 


help [command ...] 


clockdiff host ... 


msite [host ...] 
trace {on | off} 
election host 


quit Exit from timedc 


Print ashort description of each command specified in the argument list or, if no 
arguments are given, alist of the recognized commands. 

Compute the differences between the clock of the host machine and the clocks of the 
machines given as arguments. 

Show the master time server for specified hosts. 

Enable or disable the tracing of incoming messages to timed in thefile 

Asks the daemon on the target host to reset its “election” timers and to ensure that a 
time master has been elected. 


Other commands may be included for use in testing and debugging timea; the hdp command and the program source may 


be consulted for details. 


FILES 


/var/log/timed.1og tracing file for timed 


/var/log/timed.masterlog log file for master timed 


SEE ALSO 


date(1), adjtime(2), icmp(4), timed(8), “TSP: The Time Synchronization Protocol for UNIX 4.3 BSD,” R. Gusella, S. Zatti. 


DIAGNOSTICS 


?Ambiguous command 
2?Invalid command 


?Privileged command 


HISTORY 


Abbreviation matches more than one command 
No match found 
Command can be executed by root only 


The timede command appeared in BSD 4.3. 


traceroute 
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traceroute— Print the route that packets take to the network host. 


SYNOPSIS 


traceroute [-m max_ttl ] [-n] [-p port] [-q nqueries ] 
[-r] [-s src_addr] [-t tos] [-w waittime] host [packetsize] 
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DESCRIPTION 


The Internet is a large and complex aggregation of network hardware, connected together by gateways. Tracking the route 
one's packets follow (or finding the miscreant gateway that’s discarding your packets) can be difficult. traceroute utilizes the 
IP protocol time-to-live field and attempts to dicit an 1cmp TIME_EXCEEDED response from each gateway along the path to 
some host. 


Theonly mandatory parameter is the destination hostname or IP number. T he default probe datagram length is 38 bytes, 
but this can be increased by specifying a packet size (in bytes) after the destination hostname 


O ther options are 


-m maxtt | Sé& the max time-to-live (max number of hops) used in outgoing probe packets. The 
default is 30 hops (the same default used for TCP connections). 

-n Print hop addresses numerically rather than symbolically and numerically (saves a 
nameserver address-to-name lookup for each gateway found on the path). 

-p port Set the base UD P port number used in probes (default is 33434). traceroute hopes that 


nothing is listening on U DP ports base to base +nhops -1 at the destination host (so an 
ICMP PORT_UNREACHABLE message will be returned to terminate the route tracing). If 
something is listening on a port in the default range, this option can be used to pick an 
unused port range. 

-q nqueries Se the number of probes per tt1 to nqueries (default is three probes). 

-r Bypass the normal routing tables and send directly to a host on an attached network. If 
the host is not on adirectly attached network, an error is returned. T his option can be 
used to ping alocal host through an interface that has no route through it (for example 
after the interface was dropped by routed(8)). 

-s src_addr Use the following | P address (which must be given as an |P number, not a hostname) as 
the source address in outgoing probe packets. On hosts with more than one |P address, 
this option can be used to force the source address to be something other than the IP 
address of the interface the probe packet is sent on. If the IP address is not one of this 
machine's interface addresses, an error is returned and nothing is sent. 

-t tos Se the type of-service in probe packets to the following value (default zero). The value 
must be a decimal integer in the range @ to 255. T his option can be used to see if 
different types of service result in different paths. (If you arenot runningaBSD 4.3 
tahoe or later systen, this may be academic because the normal network services such as 
Telnet and FTP don’t let you control the TOS). N ot all values of TOS are legal or 
meaningful; see the IP spec for definitions. U seful values are probably (1ow delay) and 
(high throughput). 


“V Verbose output. Recaved ICM P packets other than TImE_EXCEEDED and UNREACHABLES are 
listed. 
-W Set the time (in seconds) to wait for a response to a probe (default is 3 seconds). 


This program attempts to trace the route an IP packet would follow to some Internet host by launching UD P probe packets 
with asmall tt1 (time to live) and then listening for an ICM P “time exceeded” reply from a gateway. W estart our probes 
with att1 of one and increase by one until we g& an ICM P “port unreachable” (which means we got to “host”) or hit a max 
(which defaults to 30 hops and can be changed with the -m flag). T hree probes (changed with the -q flag) are sent at each tt1 
setting and a line is printed showing the tt1, address of the gateway, and round-trip time of each probe. If the probe answers 
come from different gateways, the address of each responding systen will be printed. If there is no response within a three 
second time-out interval (changed with the -w flag), a * is printed for that probe 


W edon’t want the destination host to process the UD P probe packets, so the destination port is set to an unlikely value (if 
some clod on the destination is using that value it can be changed with the -p flag). 


traceroute jan | 


A sample use and output might be 


[yak 71]% traceroute nis.nsf.net. 
traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 

56 byte packet 
helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms ms 
lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 
lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 
ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms 
ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms 
128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 
131.119.2.5 (1381.119.2.5) 59 ms 59 ms 59 ms 
129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 
129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms 
10 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms 
11. nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 


ONOaR WON = 


o 


N ote that Lines 2 and 3 are the same. T his isdue to a buggy Kernel on the second hop system— 1b1-csam.arpa— that 
forwards packets with a zero tt1 (a bug in the distributed version of 4.3 BSD). N ote that you have to guess what path the 
packets are taking cross-country because the N SFN et (129.140) doesn’t supply address-to-name translations for its N SSs, 


A more interesting example is 


[yak 72]% traceroute allspice.lcs.mit.edu. 

traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max 

1 helios.ee.lbl.gov (128.3.112.1) @ms @ms ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 
5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 
6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 

7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms 

8 129.140.70.13 (129.140.70.13) 82 ms 79 ms 99 ms 

9 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms 

10 129.140.81.7 (129.140.81.7) 199 ms 182 ms 300 ms 

11. 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 

12 xk kk 

13 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms 

14 xk kk 


18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 


N ote that the gateways 12, 14, 15, 16, and 17 hop away. Either don’t send IC M P “time exceeded” messages or send then 
with att1 too small to reach us. Lines 14-17 are running theM IT C Gateway code that doesn’t send “time exceaded’”s. God 
only knows what's going on with 12. 


The silent gateway 12 may be the result of abug in the 4.[23] BSD network code (and its derivatives): 4.x (x <= 3) sends an 
unreachable message using whatever tt1 renains in the original datagram. Because for gateways the renaining tt1 is zero, the 
ICM P “time exceeded” is guaranteed to not make it back to us. T he behavior of this bug is sightly more interesting when it 
appears on the destination system: 


helios.ee.lbl.gov (128.3.112.1) @ms @ms ms 
lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19ms 39 ms 
lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 
ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 
ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 
csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 


aK 


ONoahwn = 


aK 
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Q *** 


10 *** 


1 o*** 


12 * * * 


13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms 
! 


N otice that there are 12 “gateways” (13 is the final destination) and exactly the last half of them are “missing.” W hat’s really 
happening is that rip (a Sun-3 running Sun O $3.5) isusing thett1 from our arriving datagram as the tt1 in its ICM P reply. 
The reply will time out on the return path (with no notice sent to anyone because IC M Ps aren’t sent for ICM Ps) until we 
probe with a tt1 that’s at least twice the path length. That is, rip is really only seven hops away. A reply that returns with a 
ttl of 1 isaclue this problem exists. traceroute prints a! after the time if the tt1 is less than or equal to 1. Because vendors 
ship alot of obsolete (DEC Ultrix, Sun 3.x) or non-standard H PU X software, expect to see this problem frequently or take 
care picking the target host of your probes. O ther possible annotations after thetime are !H, !n, !P (got a host, network, or 
protocol unreachable), !s, or !F (source route failed or fragmentation needed— nather of these should ever occur and the 
associated gateway is busted if you see one). If almost all the probes result in some kind of unreachable, traceroute will give 
up and exit. 


This program is intended for use in network testing, measurement, and management. It should be used primarily for manual 
fault isolation. Because of the load it could impose on the network, it is unwise to use traceroute during normal operations 
or from automated scripts. 


AUTHOR 


Implemented by Van J acobson from a suggestion by Steve D eering. D ebugged by a cast of thousands with particularly 
cogent suggestions or fixes from C. Philip W ood, Tim Seaver, and Ken Adelman. 


SEE ALSO 


netstat(1), ping(8) 
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tune2ts 


tune2ts— Adjust tunable filesystem parameters on second extended filesystems. 


SYNOPSIS 
tune2fs [ -1 ][-c max-mount-counts ][-e errors-behavior ] 
[-iinterval-between-checks ][ -mreserved-blocks-percentage ] 
[-r reserved-blocks-count ][-u user ][-g group ]device 
DESCRIPTION 


tune2fs adjusts tunable filesystem parameters on a Linux second extended filesystem. 
N ever use tune2fs on aread/write mounted filesystem to change parameters! 


OPTIONS 
-C max-mount- counts Adjust the maximal mounts count between two filesystem checks. 
-e errors-behavi or Change the behavior of thekernel code when errors are detected. errors- behavior Can 
be one of the following: 
continue Continue normal execution. 
remount -ro Remount the filesystem read-only. 


panic Causes a kernd panic. 


tundp 


-g group Set the user group that can benefit from the reserved blocks. group can be anumerical 
GID or agroup name 

-i interval-between-checks [dim'w] Adjust the maximal time between two filesystem checks. N o postfix or d results in days, 
min months, and w in weeks. A value of @ will disable thetime dependent checking. 


-1 List the contents of the filesystem superblock. 
-m reserved- bl ocks-percentage Adjust the reserved blocks percentage on the given device. 
-r reserved- blocks-count Adjust the reserved blocks count on the given device 
-u user Se the user who can benefit from the reserved blocks. user can beanumerical UID ora 
username. 
BUGS 
W edidn’t find any bugs. Perhaps there are bugs, but it’s unlikely. 
WARNING 
Use this utility at your own risk. You’re modifying filesystems. 
AUTHOR 


tune2fs was written by Reny Card (card@masi.ibp.fr), the develope and maintainer’ of the ext2 filesystem. tune2fs 
uses the ext2fs library written by Theodore T’so (tytso@mit.edu). This manual page was written by Christian K uhtz 
(chk@data-hh.Hanse.DE). Time-dependent checking was added by U we O hse (uwe@tirka.gun.de). 


AVAILABILITY 


tune2fs is available for anonymous FT P from ftp. ibp.fr and tsx-11.mit.edu iN /pub/linux/packages/ext2fs. 


SEE ALSO 


dumpe2ts(8), e2fsck(8), mke2ts(8) 


Verdon 0.5b, N ovenber 1994 


tunelp 


tunelp— Se various parameters for thelp device. 


SYNOPSIS 
tunelp device [-i 1RQ | -t TIME | -c CHARS 
; -w WALT | -a [onjoff] | -o [onjoff] | -C [onjoff] 
1 Py -S 7 -q [onjoff] ] 

DESCRIPTION 


tunelp sets several parameters for the /dev/1p? devices, for better performance (or for any performance at all, if your printer 
won't work without it... ). Without parameters, tunelp tells whether the device is using interrupts, and if so, which one. 
With parameters, tunelp sets the device characteristics accordingly. The parameters are as follows: 


-i <I RQ> TheIRQ to usefor the parallel port in question. If this is set to something nonzero, -t 
and -c haveno effect. If your port does not use interrupts, this option will make 
printing stop. tunelp -i @ restores non-interrupt driven (polling) action, and your 
printer should work again. If your parallel port does support interrupts, interrupt-driven 
printing should be somewhat faster and efficient and will probably be desirable 

-t <TIME> The amount of time in jiffies that the driver waits if the printer doesn’t take a character 
for the number of tries dictated by the -c parameter. 10 is the default value. If you want 
the fastest possible printing and don’t care about system load, you can set this to o. If 
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you don’t care how fast your printer goes or are printing text on aslow printer with a 
buffer, then 500 (5 seconds) should be fine and will give you very low systen load. This 
value generally should be lower for printing graphics than text, by a factor of approxi- 
mately 10, for best performance. 

-c <CHARS> Thenumber of times to try to output a character to the printer before sleeping for 
-t <T| ME>. [tis the number of times around a loop that tries to send a character to the 
printer. 120 appears to be a good value for most printers. 250 is the default because there 
are some printers that require a wait this long, but feel free to change this. If you havea 
very fast printer like an H P Laserjet 4, a value of 12 might make more sense If you have 
a really old printer, you can increase this. 

Setting -t <TI ME> to @ is equivalent to setting -c <CHARS> to infinity. 

-w <WAIT> The busy loop counter for the strobe signal. Although most printers appear to be able to 
deal with an extremely short strobe, some printers demand a longer one. Increasing this 
from the default might make it possible to print with those printers. T his can also 
make it possible to use longer cables. 

-a [onloff] This is whether to abort on printer error; the default is not to. If you are sitting at your 
computer, you probably want to be able to see an error and fix it and have the printer go 
on printing. On the other hand, if you aren’t, you might rather that your printer spooler 
find out that the printer isn’t ready, quit trying, and send you mail about it. The choice 
iS YOUTS. 

-o [onloff] This option is much like -a. It makes any open() of this device check to see that the 
device is online and not reporting any out-of-paper or other errors. This is the correct 
setting for most versions of ipa. 

-C [ontoff] This option adds extra (“careful”) error checking. W hen this option is on, the printer 
driver will ensure that the printer is online and not reporting any out-of-paper or other 
errors before sending data. T hisis particularly useful for printers that usually appear to 
acceot data when turned off. 

-s This option returns the current printer status, both asa decimal number from 0 to 255 
and as a list of active flags. W hen this option is specified, -q off, turning off the display 
of the current IRQ, is implied. 

-o, -C, and -s all require a Linux kernel version of 1.1.76 or later. 
-r This option resets the port. It requires a Linux kernd version of 1.1.80 or later. 
-q [ontoff] This option sets printing the display of the current IRQ setting. 


Cohedve Systens, 26 August 1992 


update state 
update_state— U pdate system state. 


SYNOPSIS 


update_state 


DESCRIPTION 
update_state updates a bunch of system states. It takes along time to execute and would be suitable for execution in acron 
job. 
Currently, update_state performs the following functions: updates the locate database (in /usr/1ib/locate), updates the 


whatis database(in /usr/man, /usr/local/man, /usr/X386/man, aNd /usr/interviews/man), and updates the T eX 1s-r cache file 
(in /usr/lib/texmf). 


uucico 
BUGS 


The script expects things to be where the FSSTND saysthey are. For example, if you have makewhatis(8) in /usr/1ib, where 
it istraditionally, then you lose because it should bein /usr/bin. 


SEE ALSO 


cron(8), find(1), locate(1) 


AUTHOR 


Rik Faith (faith@cs.unc. edu) 
Linux 1.0 8, July 1994 


uuC1CO 


uucico— UUCP file transfer daemon. 


SYNOPSIS 


uucico [ options ] 


DESCRIPTION 


The uucico daanon processes file transfer requests queued by uucp(1) and uux(1). It is started when uucp or uux iS run (unless 
they are given the -r option). It is also typically started periodically using entries in the crontab tables. 


When invoked with -r1, --master, -s, --system, or -s, the daemon will place a call to a ranote system, running in master 
mode Otherwise, the daenon will start in slave mode, accepting acall from a remote system. T ypically, a special login name 
will be set up for UUCP, which automatically invokes uucico when a call is made. 


W hen wucico terminates, it invokes the uuxqt(8) daemon, unless the -q or - -nouuxqt option is given; uuxqt(8) executes any 
work orders created by uux(1) on a remote system and any work orders created locally that have recaved remote files for 
which they were waiting. 


If a call fails, uucico will usually refuse to retry the call until a certain (configurable) amount of time has passed. This may be 
overridden by the -f, -force, or -s option. 


The -1, --prompt, -e, OF --loop options may be used to force uucico to produceits own prompts of login: and Password:. 

W hen another daenon calls in, it will see these prompts and log in as usual. The login name and password are usually 
checked against a separate list kept specially for uucico rather than the /etc/passwa file it is possible on some systems to 
direct uucico to use the /etc/passwd file. The -1 or -prompt option will prompt once and the exit; in thismode theUUCP 
administrator or the superuser may use the -u or -1ogin option to forcea login name in which case uucico will not prompt 
for one. The -e or -1oop option will prompt again after the first session is over; in thismode, uucico will permanently control 
a port. 


If uucico rece ves a SIGQUIT, SIGTERM, OF SIGPIPE signal, it will cleanly abort any current conversation with a remote system 
and exit. If it receives a stcHuP signal, it will abort any current conversation, but will continue to place calls to (if invoked 
with -r1 or --master) and accept calls from (if invoked with -e or --1oop) other systems. If it receives asiainT signal, it will 
finish the current conversation but will not place or accept any more calls. 


OPTIONS 


The following options may be given to uucico: 


-r1, ---master Start in master mode (call out to a system); implied by -s, --system, or -s. If no system 
is specified, call any system for which work is waiting to be done. 
-rQ, ---slave Start in slavemode. T his isthe default. 


-s system, ---system system Call the named system. 
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-S system 
-f, ---force 
-1, ---prompt 


-p port, ---port port 
-e, ---loop 


-w, ---wait 


-q, ---nouuxgt 


-C, ---quiet 

-C, ---ifwork 

-D, ---nodetach 

-u name, ---login name 


-Z, ---try-next 


-itype, ---stdin type 


-x type, -X type, ---debug type 


-I file, ---config file 


-V, ---version 
--help 


-u login 


FILES 


Call the named system, ignoring any required wait. This is equivalent to -s system -f. 
Ignore any required wait for any systems to be called. 

Prompt for login name and password using login: and Password:. T his allows uucico to 
be easily run from ineta(8). The login name and password are checked against the 
UUCP password file, which probably has no connection to thefile /etc/passwa. T he 
--login option may be used to force alogin name, in which case wucico will only 
prompt for a password. 

Specify a port to call out on or to listen to. 


Enter endless loop of login/password prompts and slave mode daemon execution. The 
program will not stop by itself; you must use ki11(1) to shut it down. 

After calling out (to a particular system when -s, --system, or -S is specified or to all 
systems that have work when just -r1 or --master is specified), begin an endless loop as 
with --1loop. 

Do not start the uuxqt(8) daemon when finished. 


If no calls are permitted at thistime, then don’t make the call, but also do not put an 
error message in the log file and do not update the system status (as reported by 
uustat(1)). T his can be convenient for automated polling scripts, which may want to 
simply attempt to call every systen rather than worry about which particular systens 
may be called at the moment. This option also suppresses the log message indicating 
that there is no work to be done. 

Only call the system named by -s, --system, or -s if there is work for that system. 

Do not detach from the controlling teminal. N ormally, uucico detaches from the 
terminal before each call out to another system and before invoking uuxat. This option 
prevents this. 

Sé@ the login name to use instead of that of the invoking user. This option may only be 
used by the UUCP administrator or the superuser. If used with --prompt, this will cause 
uucico to prompt only for the password, not thelogin name 

If a call fails after the remote system is reached, try the next alternate rather than amply 
exiting. 

Se the type of port to use when using standard input. The only support port type is 
TLI, and this is only available on machines that support the T LI networking interface. 
Specifying -iTLI Causes uucico to useTLI calls to perform I/O. 

Turn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 

M ultiple types may be given, separated by commas, and the - -debug option may appear 
multiple times. A number may also be given, which will turn on that many types from 
the foregoing list; for example, --debug 2 is equivalent to --debug abnormal, chat. 

The debugging output is sent to the debugging file usually one of /usr/spoo1/uucp/ Debug, 
/usr/spool/uucp/DEBUG, OF /usr/spool/uucp/.Admin/audit.local. 

Sé& configuration file to use This option may not be available depending on how 
uucico was compiled. 

Report version information and exit. 

Print ahap message and exit. 


This option is ignored. It is only included because some versions of uucpd invoke uucico 
with it. 


The filenames may be changed at compilation time or by the configuration file, so these are only approximations: 


/usr/1lib/uucp/config 
/usr/lib/uucp/passwd 


Configuration file. 
Default UU CP password file. 


vmstat 1417 


/usr/spool/uucp UUCP spool directory. 
/usr/spool/uucp/Log UUCP log file 
/usr/spool/uucppublic Default UUCP public directory. 
/usr/spool/uucp/Debug Debugging file 

SEE ALSO 
kil1(1), uucp(1), uux(1), uustat(1), uuxqt(8) 

AUTHOR 


lan Lance T aylor (ian@airs.com) 
Taylor UUCP 1.05 


vmstat 

vmstat— Report virtual memory statistics. 
SYNOPSIS 

vmstat [ -n ] [ delay [ count ] ] 
DESCRIPTION 


vmstat reports information about processes, memory, paging, block 10, traps, and CPU activity. 
The first report produced gives averages since the last reboot. Additional reports give information on a sampling period of 
length dday. The process and memory reports are instantaneous in eather case. 


OPTIONS 
The -n switch causes the header to be displayed only once rather than periodically. 


del ay isthe delay between updates in seconds. If no dday is specified, only one report is printed with the average values since 
boot. 


count isthe number of updates. If no count is specified and del ay isdefined, count defaults to infinity. 


FIELD DESCRIPTIONS 











Procs 

r The number of processes waiting for runtime 

b Thenumber of processes in uninterruptible sleep. 

w Thenumber of processes swapped out but otherwise runnable 

This fidd is calculated, but Linux never desperation swaps. 

M emory 

swpd The amount of virtual memory used (KB). 

free The amount of idle memory (KB). 

buff The amount of memory used as buffers (KB). 
Swap 

si Amount of memory swapped in from disk (KB/s). 


$0 Amount of menory swapped to disk (KB/s). 
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10 
bi Blocks sent to a block device (blocks/s). 
bo Blocks recaved from a block device (blocks/s). 
System 
in Thenumber of interrupts per second, including the clock. 
cs Thenumber of context switches per second. 


CPU (These are percentages of total CPU time) 





us Use time 

sy System time. 

id Idle time. 
NOTES 


vmstat does not require special permissions. 
T hese reports are intended to help identify system bottlenecks. Linux vmstat does not count itself as a running process. 
All Linux blocks are currently 1K B, except for CD-ROM blocks, which are 2KB. 

FILES 


/proc/meminfo 
/proc/stat 
/proc/*/stat 


SEE ALSO 
ps(1), top(1), free(1) 


BUGS 


vmstat does not tabulate the block 10 per device or count the number of system calls. 


AUTHOR 
Written by H enry W are (al172@yfn. ysu.edu) 
T hroatwobble Ginkgo Labs 27 July 1994 


Vipw 
vipw— Edit the password file. 


SYNOPSIS 


vipw 


DESCRIPTION 
vipw edits the password file after setting the appropriate locks and does any necessary processing after the password file is 
unlocked. If the password file is already locked for editing by another user, vipw will ask you to try again later. T he default 
editor for vipw isvi(1), 


. 


ENVIRONMENT 
If the following environment variable exists, it will be utilized by vipw: 
EDITOR The editor specified by the string. en1Tor will be invoked instead of the default editor 
vi(1). 
SEE ALSO 
passwd(1), vi(1), passwa(5) 
HISTORY 


The vipw command appeared in BSD 4.0. 
BSD 4, 16 M arch 1991 


zdump 


zdump— T ime zone dumper. 


SYNOPSIS 


zdump [ -v ][-c cutoffyear ] [ zonename ... ] 


DESCRIPTION 


zdump prints the current time in each zonename named on thecommand line 
T hese options are available: 


“V For each zonename On the command line, print the current time, the time at the lowest 
possible time value, the time one day after the lowest possible time value, the times both 
one second before and exactly at each detected time discontinuity, the time at one day 
less than the highest possible time value, and the time at the highest possible time value. 
Each line ends with isdst=1 if the given timeis D aylight Saving Time or isdst=0 


otherwise 

-c cutoffyear Cut off the verbose output near the start of the given year. 
SEE ALSO 

newctime(3), tzfile(5), zic(8) 
Z1C 

zic— Timezone compiler. 
SYNOPSIS 

zic [ -v ][-d directory ][-l localtime ][-p posixrules ] 

[-L leapsecondfilename ][-s ] [ -y command ][filename ... ] 
DESCRIPTION 


zic reads text from the files named on the command line and creates the time conversion information files specified in this 
input. If a filename is -, the standard input is read. 


T hese options are available: 


-d directory Create time conversion information files in the named directory rather than in the 
standard directory named below. 
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= 


i mezone 


imezone 


nol 





rc 


eapsecondfil ename 


-y command 


Use the given time zone as local time zic will act as if the input contained alink line of 
the form. 


Link timezone localtime. 


Use the given time zone's rules when handling PO SIX-format time zone environment 
variables. zic will act asif the input contained a link line of the form. 


Link timezone posixrules. 


Read leap second information from the file with the given name. If this option is not 
used, no leap second information appears in output files. 

Complain if a year that appears in a data file is outside the range of years representable 
by time(2) values. 

Limit time values stored in output files to values that are the same whether they're taken 
to be signed or unsigned. You can use this option to generate SV V S-compatible files. 
Use the given command rather than yearistype when checking year types. 


Input lines are made up of fields. Fidds are separated from one another by any number of whitespace characters. Leading 
and trailing whitespace on input lines isignored. An unquoted sharp character (#) in the input introduces a comment that 
extends to the end of the line the sharp character appears on. Whitespace characters and sharp characters may be enclosed in 
double quotes (") if they're to be used as part of afield. Any line that is blank (after comment stripping) is ignored. N on- 
blank lines are expected to be of one of three types: rule lines, zone lines, and link lines. 


A rulelinehasthe form 


Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/ S 


For example: 


Rule US 1967 1973 - Apr lastSun 2:00 1:00 D 


The fields that make up arule line are 


NAME 
FROM 


T0 


TYPE 


IN 
ON 


Gives the (arbitrary) name of the set of rules this rule is part of. 

Gives the first year in which the rule applies. Any integer year can be supplied; the 
Gregorian calendar is assumed. The word minimum (or an abbreviation) means the 
minimum year representable as an integer. The word maximum (or an abbreviation) means 
the maximum year representable as an integer. Rules can describe times that are not 
representable as time values, with the unrepresentable times ignored; this allows rules to 
be portable among hosts with differing time value types. 

Gives the final year in which the rule applies. In addition to minimum and maximum, 
the word only (or an abbreviation) may be used to repeat the value of ther rom fidd. 
Gives the type of year in which the rule applies. If type is -, the rule applies in all years 
between FROM and To inclusive If type is something else then zic executes the command 
yearistype year type 

to check the type of a year. An exit status of zero is taken to mean that the year is of the 
given type; an exit status of oneis taken to mean that the year is not of thegiven type. 

N ames the month in which the rule takes effect. M onth names may be abbreviated. 
Gives the day on which the rule takes effect. R ecognized forms include 


5 The fifth of the month 

lastSun Thelast Sunday in the month 
lastMon The last M onday in the month 
Sun>=8 First Sunday on or after the eighth 
Sun<=25 Last Sunday on or before the 25th 


N ames of days of the week may be abbreviated or spelled out in full. 
N ote that there must be no spaces within theon field. 


‘ 


AT Gives the time of day at which therule takes effect. Recognized forms include 
2 Timein hours 
2:00 Timein hours and minutes 
15:00 24-hour format time (for times after noon) 
1:28:14 Timein hours, minutes, and seconds 


Any of these forms may be followed by the letter w if the given time is local wall clock 
time, s if thegiven timeislocal standard time, or u (or g or z) if the given timeis 
universal time; in the absence of an indicator, wall clock time is assumed. 


SAVE Gives the amount of time to be added to local standard time when the rule is in effect. 
This fidd has the same format as theat fidd (although, of course, thew and s suffixes 
are not used). 

LETTERS Gives the variable part (for example, thes orp in EST or EDT) of timezone abbrevia- 


tions to be used when this ruleis in effect. If this field is -, the variable part is null. 


A zone line has the form 
Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] 





For example: 
Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 


The fields that make up azonelineare 


NAME Thename of the timezone Thisis the name used in creating the time conversion 
information file for the zone. 
GMT OFF The amount of time to add to GMT to get standard time in this zone. This field has the 


same format asthe at and save fields of rule lines, begin the field with a minus sign if 
time must be subtracted from GMT. 


RULES] SAVE Thename of the rules that apply in the time zone or, alternately, an amount of time to 
add to local standard time If this fidd is -, standard time always applies in the time 
zone. 

FORMAT The format for timezone abbreviations in this timezone The pair of characters %s is 


used to show where the variable part of the timezone abbreviation goes. Alternately, a 
slash (/) separates standard and daylight abbreviations. 


UNTIL The time at which the GMT offset or the rules change for a location. It is specified as a 
year, amonth, a day, and atime of day. If thisis specified, the timezone information is 
generated from the given GM T offset and rule change until the time specified. 


The next line must be a continuation line this has the same form as a zone line except 
that the string Zone and the name are omitted because the continuation line will place 
information starting at the time specified as theuntit field in the previous linein the file 
used by the previous line. Continuation lines may contain an untiL fidd, just as zone 
lines do, indicating that the next line is a further continuation. 

A link line hastheform 


Link LINK-FROM LINK-10 
For example: 


Link US/Eastern EST5EDT 


The Li nk- FROM field should appear asthename fidd in some zoneline; thet! nk-T0 field is used as an alternate name for that 
zone. 


Except for continuation lines, lines may appear in any order in the input. 
Linesin the file that describe leap seconds have the following form: 


Part VIII: Administration and Privileged Commands 


Leap YEAR 


For example: 


Leap 1974 


The year, 


ONTH DAY HH: MM: SS CORR R/S 


Dec 31 23:59:60 + S 


ONTH, DAY, ANC HH: MM: SS fields tell when the leap second happened. Thecorr fidd should be + if a second was 


added or - if asecond was skipped. Ther/s field should be (an abbreviation of) stationary if the leap second time given by 
the other fields should be interpreted as GMT or (an abbreviation of) Rolling if the leap second time given by the other 
fidds should be interpreted as local wall clock time 


NOTE 





For areas with more than two types of local time, you may need to use local standard timein theat field of the earliest 


transition 


FILE 


time's rule to ensure that the earliest transition time recorded in the compiled file is correct. 


/usr/local/etc/zoneinfo Standard directory used for created files. 


SEE ALSO 


newctime(3), tzfile(5), zdump(8) 
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add timer,del timer, init_timer 


add_timer, del_timer, init_timer— M anage event timers. 


SYNOPSIS 


#include <asm/param.h> 

#include <linux/timer.h> 

extern void add_timer(struct timer_list * timer); 

extern int del_timer(struct timer_list * timer); 

extern inline void init_timer(struct timer_list * timer); 


DESCRIPTION 


add_timer schedules an event, adding it to a linked list of events maintained by the kernd. dei_timer deletes a scheduled 
event. timer points to a 


struct timer_list { 

struct timer_list *next; 

struct timer_list *prev; 
unsigned long expires; 

unsigned long data; 

void (*function) (unsigned | ong); 
}; 


init_timer S&Snext and prev to nuLL. T hisis required for the argument of add_timer. expires isthedesired duration of the 
timer in jiffies, where there are Hz (typically 100) jiffies per second. When the timer expires, function iS called with data as 
its argument. It is the responsibility of function to ddete the event. If the same function is managing several timers, the 
argument can be used to distinguish which one expired. 


RETURN VALUE 


del_timer returns zero on error— if next Or prev are not NULL, but the timer was not found. de1_timer also sets expires to the 
time remaining before the timer expires and sets next and prev to NULL. T hus, calling de1_timer followed immediately by 
add_timer iSano-op provided a kernel tick does not occur between the two calls. 


AUTHOR 


Linus Torvalds 
Linux 1.2.8, 31 May 1995 


adjust_clock 


adjust_clock— Adjusts startup time counter to tick in GMT. 


SYNOPSIS 


linux/kernel/sys.c 
void adjust_clock(); 


DESCRIPTION 


This routine adjusts the startup time by adding the time zone information to it. The goal isto get the startup time ticking in 
GMT time 


NOTES 


This routine is called from settimeofday(2) when thetime-zone information is first set. 


AUTHOR 


TheodoreT 'so (tytso@mit.edu) 


SEE ALSO 


settimeofday(2) 


ct 


ctr1_alt_de1— Routes the keyboard interrupt C trl-+Alt+D el key sequence 


rl alt_del 


SYNOPSIS 


linux/kernel/sys.c 
void ctrl_alt_del(void) ; 


DESCRIPTION 


This simple routine tests the variablec_A_o for a true/false condition. If it is true, a hard reset is done by the systen. 
Otherwise, asignal staint is sent to the process with the process!D 1, usually a program called init. 


WARNINGS 


This routineisin interrupt mode It cannot sync() your system. D ata loss may occur. It is recommended that you configure 


your system to send a signal to init, where you can control the shutdown. 


NOTES 
The default of this function is to do hard resets immediatdy. 


AUTHOR 


Linus Torvalds 


SEE ALSO 


reboot(2), reset_hard_now(9), sync(2) 


TL 


f 


le table 


ile_table— D etailed description of the table and table entry. 


SYNOPSIS 


From #include <linux/fs.h> 


s 
m 
d 
0 
u 
u 
u 
s 
s 


ruct file { 

ode_t f_mode; 

ev_t f_rdev; /* needed for /dev/tty */ 
f_t f_pos; 

nsigned short f_flags; 

nsigned short f_count; 

nsigned short f_reada; 

ruct file *f_next, *f_prev; 

ruct inode *f_inode; 





file table 


Linux 0.99.10, 7 July 1993 


Linux 0.99.10, 6 July 1993 
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struct file_operations *f_op; 
hs 


From linux/fs/file_table.c 


struct file *first_file; 
int nr_files = Q; 


DESCRIPTION 


The file table is fundamentally important to any UNIX system. It is where all open files (Linux includes closed files as wall) 
are stored and managed by thekernel. For Linux, you can hardly do anything without referencing it in some way. 


Linux stores its file table as a double circular linked list. The root pointer to the “head” of this list isfirst_file. Also, acount 
of how many entries are in the file table is maintained, called nr_files. Under this scheme, the file table for Linux could be 
as large as memory could hold. Unfortunately, this would be unmanageable in most cases. Your computer would bein the 
kernd most of the time when processes are more important. T o keep this from happening, nr_files is tested against NR_FILE 
to limit the number of file table entries. 


UNDERSTANDING THE STRUCTURE OF THE FILE TABLE 


The file table is organized as a double circular linked list. | maginea circle of people with everyone facing the same direction. 
Each person is facing so that one arm isin the circle and the othe arm is outside the circle N ow, if each person put his or 
her right hand on the shoulder of the person in front of him or her and if each person touched the person behind him or her 
with his or her left hand. You have formed two circles of arms, one inside and the other outside. T he right arms represent 
pointers to the next entry (or person). The left arms represent pointers to the previous entry (or person). 


THE FILE STRUCTURE, A FILE TABLE ENTRY 


At first glance, a table entry looks quite simple. An entry contains how a file was opened, what tty device, a reference count, 
pointers to other entries, pointer to v-node (the vfs i-node) filesystem-specific i-node information, and so on. 





f_mode After AN Ding with 0 accmope, this is what bits 0 and 1 mean: 
00 N 0 permissions needed 
01 Read-permission 
10 W rite permission 
11 Read-write 
_rdev It is used only with tty lines. It contains the major and minor numbers of the tty device. 
_pos The current position in afile if meaningful. 
flags Storage for the flags from open() and fent1() 
count Reference counter 
_reada This is a Boolean variable where True means that an actual read is needed. 
next, f_prev Pointers to other entries 
_inode Pointer to v-node and filesystem-specific i-node information 
op Pointer to a file’s operations 
AUTHOR 
Linus Torvalds 
SEE ALSO 


insert_file free(9), remove file free(9), put_last_free(9) grow files(9), file table init(9), get_empty_filp(9) 
Linux 0.99.10, 11 July 1993 
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file table init 


file _table_init— Initializes the file table in the kend. 


SYNOPSIS 


linux/fs/file_table.c unsigned long file_table init( 
unsigned long start, unsigned long end); 


DESCRIPTION 


This routine is called from kernel_start() iN linux/init/main.c. It sets first_file, astruct file pointer, to NULL. Thisis the 
head of the linked list of open files maintained in the kernal, the infamous file table in all UN IXs. 


RETURN VALUE 


ReturnSstart. 


NOTES 


Because this is part of the kernal’s startup routine, it has the option to allocate memory, in kernel space for itself. It does not 
need to do this and returns the new start of memory for the next initializing section. In this case start is returned unmodi- 
fied. 

AUTHOR 


Linus Torvalds 
Linux 0.99.10, 9 July 1993 


filesystems 


filesystems— D etails the table of configured filesystems. 


SYNOPSIS 


linux/fs/filesystems.c 


From #include <linux/fs.h> 


struct file systemtype { 

struct super _block *(*read_super) (struct super_block *, void *, int); 
char *name; 

int requires dev; 


ie 
DESCRIPTION 


This source code makes a data structure call file_systems{], which contains all the configured filesystems for the kernel. It is 
used primarily in 1inux/fs/super.c for many of the mounting of filesystems functions. 


THE MEANINGS 


This first member, in struct file system type, iSa function pointer to aroutine that will readin thesuper_block.A 
super_block generically means an i-node or special place on the device where information about the overall filesystem is 
stored. 


Thename iS just the string representation of the name of a specific filesystem, such as ext2 Or minix. 


Thefinal membey, i nt_requires_dev, iS a Boolean value. If it is True, then the filesystan requires a block device For False, it 
is unclear what happens, but an unnamed deviceis used, such aS proc and nfs. 
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AUTHOR 


Linus Torvalds 
Linux 0.99.10, 12 July 1993 


get_empty filp 
get_empty_filp— Fetches an unreferenced entry from the file table. 


SYNOPSIS 


linux/fs/file table.c 
struct file *get_empty_filp(void) ; 


DESCRIPTION 


This routine will seek out an entry that isnot being referenced by any processes. If none are found, then it will add new 
entries to the file table, minimum of nr_FILE entries, 


NOTES 


D ueto grow files(), a whole page of entries is created at onetime. T hismay make more than nr_FILe entries. Also when an 
unreferenced entry is found, it is moved to the “end” of the file table. This heuristic is used to speed up finding unreferenced 
entries. 


RETURN VALUE 
NULL— N o entries were found and the file table is full. 
Returns a pointer to the entry in thefile table 


AUTHOR 


Linus Torvalds 


SEE ALSO 


grow _files(9) 
Linux 0.99.10, 12 July 1993 


grow files 
grow_files— Adds entries to the file table. 
SYNOPSIS 


linux/fs/file table.c 
void grow _files(void) ; 


DESCRIPTION 


This function adds entries to the file table First, it allocates a page of memory. It fills the entire page with entries, adding 
each to the file table. 


AUTHOR 


Linus Torvalds 


insert_ file free 


Linux 0.99.10, 12 July 1993 


SEE ALSO 


insert_file free(9), remove file free(9), put_last_free(9) 


in_group_p 
in_group_p— Searches group ID s for a match. 


SYNOPSIS 


linux/kernel/sys.c 
int in_group_p(gid_t grp); 


DESCRIPTION 


Searches supplementary group IDs and the effective group ID for amatch with grp. 


RETURN VALUE 


Returns True (1) if found; otherwise, false (0). 


AUTHOR 


Linus Torvalds 


SEE ALSO 
getgroups(2), getgid(2), getregid(2), setgid(2), setregid(2), setgroups(2) 
Linux 0.99.10, 7 July 1993 


insert_file free 


insert_file_free— Adds a file entry into the file table. 


SYNOPSIS 


linux/fs/file_table.c 
static void insert_file free(struct file *file); 


DESCRIPTION 


This nightmare of pointers adds fi!e into the file table with the root pointer at ti! e. Thisisa building block of the file table 
management. 


AUTHOR 


Linus Torvalds 
SEE ALSO 
file table init(9), remove file free(9), put_last_free(9) 
See file table(9) for details on the file table structure. 
Linux 0.99.10 
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kernel_mktime 


kernel_mktime— Convert startup struct mktime into the number of seconds since 00:00:00 J anuary 1, 1970. 


SYNOPSIS 


linux/kernel/mktime.c 
long kernel_mktime(struct mktime * time); 


DESCRIPTION 


This routine is called from time_init(void), linux/init/main.c. kernel_mktime() Converts struct mktime (initialized from 
CMOS) into an encoded long. 


CONVERSION METHOD 


First an array, month[ 12], is created, holding how many seconds have passed to reach a peculiar month for a leap year. N ext, 
it subtracts 70 from the current year, making 1970 the beginning year. It is math magic after this point; please look yourself. 
If you know why it does this, then send e-mail (see nroff source). 


RETURN VALUE 


Returns the encoded time in along. 


FILES 


linux/kernel/mktime.c homeof routine 


NOTES 
This routine is called only during startup of the kernal. 


H istorically, the value (encoded long) counts the number of seconds since the Epoch, which occurred at 00:00:00 January 1, 
1970, and is called Coordinated Universal Time (UTC). In older manuals, this event is called Greenwich M ean Time 
(GMT). 


WARNINGS 


kernel_mktime() doesn’t check to see if the year is greater than 1969. Be sure your CM OS isset correctly. It is customary to 
set on-board clocks to GMT and let processes who ask for the time to convett it to local time, if necessary. 


RESTRICTIONS 


For kernel use only. 


AUTHOR 
Linus Torvalds 
Linux 0.99.10, 5 July 1993 


proc sel 
proc_sel— Sdect a process by a criterion. 


SYNOPSIS 


linux/kernel/sys.c 
#include <linux/resource.h> 
static int proc_sel(struct task_struct *p, int which, int who); 


renove_file_ free 
DESCRIPTION 


Compares a task p to supplied information or the current task in some aspect of priority. If who iszero, the comparison is task 
p and the current task. Otherwise, who and *p are the supplied information for the comparison. 


OPTIONS 


Valid values of which: 


PRIO_PROCESS Compares process|D numbers. There is an exception here. If who isnot zero and task p is 
the current task, then True is always returned. 
PRIO_PGRP Compares process group leader numbers. 
PRIO_USER Compares user |D numbers. 
RETURN VALUE 
Returns truth values (0, 1). 
AUTHOR 
Linus Torvalds 
SEE ALSO 


sys_setpriority(2), sys_getpriority(2) 
Linux 0.99.10, 7 July 1993 


put_file last 
put_file last— M ovesafile to the “end” of thefile table 


SYNOPSIS 


linux/fs/file table.c 
static void put_last_free(struct file *file); 


DESCRIPTION 
This function will renoveti!e from the file table and insert it again at the end. You can access by 


first_file->prev 


AUTHOR 


Linus Torvalds 


SEE ALSO 


insert_file free(9), remove file free(9) 


Linux 0.99.10, 11 July 1993 


remove file free 


remove file free— Ranovea file table entry from the linked list. 


SYNOPSIS 


linux/fs/file table.c 
static void remove file free(struct file *file); 
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DESCRIPTION 


This routine removes the file from the table T hisis used mostly for moving afile to the “end” of the list. 


AUTHOR 


Linus Torvalds 


SEE ALSO 


insert_file free(9), put_file last(9) 
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* (asterik), bash special parameters 


Symbols 


* (asterisk), bash special 
parameters, 15 
@ (at sign), bash special 
parameters, 15 
\ (backslash), bash escape 
character, 14 
$ (dollar sign) 
bash special parameters, 15 
expansion, 19 
ftp command, 148 
! (exclamation point) 
bash special parameters, 15 
ftp command, 148 
! command (telnet), 512 
> (greater than sign), 
redirection operator, 21 
- (hyphen), bash special 
parameters, 15 
< (less than sign), redirection 
Operator, 21 
| (pipeline), bash, 12 
# (pound sign) 
bash comments, 14 
bash special parameters, 15 
? (question mark) 
bash special parameters, 15 
ftp command, 152 
? command 
telnet, 512 
xauth, 591 
_ (underscore), bash special 
parameters, 15 
/ directory, 1236 
0, bash special parameter, 15 
8859-1 character set, 1064 
8859-2 character set, 1064 
8859-3 character set, 1064 
8859-4 character set, 1064 
8859-5 character set, 1065 
8859-6 character set, 1065 
8859-7 character set, 1065 
8859-8 character set, 1065 
8859-9 character set, 1065 
8859-10 character set, 1065 


A 


Abekas YU V bytes, converting 
to portable pixmaps, 731 
abort( ) function, 892 
abs( ) function, 892-893 
absolute values, 892-893 
floating-point numbers, 919 
long integers, 960-961 
accept, 740-741 
access, 741-742 
errors, 741 
restrictions, 741 
return value, 741 
access control 
files, changing permissions, 
61-62 
hosts_access, 1133-1136 
diagnostics, 1136 
files, 1133, 1136 
operators, 1134 
patterns 1133-1134 
remote username lookup, 
1134-1135 
rules, 1133 
hdl commands 1134 
wildcards, 1134 
language extensions, 
1137-1139 
memory, 804-805 
NNTP sites, 1167-1168 
account (ftp command), 148 
acct, 742 
acos( ) function, 893 
acosh( ) function, 893-894 
active, 1104-1105 
active.times, 1104-1105 
add (cvs command), 96 
ADD_ADDRESS environ- 
ment variable, 529 
add_timer, 1424 
addftinfo, 2 
addgroup, 1258-1259 
addmntent( ) function, 
935-936 


addresses 
Internet, manipulating, 
953-954 
mail addressing, 1244-1246 
abbreviations 1245 
cae enstivity, 1245 
compatibility, 1245 
potmasters, 1246 
routing, 1245 
physical, accessing, 818 
sed, 476 
virtual memory, renapping, 
805-806 
adduser, 1258-1259 
adduser.conf, 1105 
adjtimex, 742-743 
adjust_clock, 1424-1425 
admin (cvs command), 96 
advisory locks, open files 
(applying/removing), 757 
afmtodit, 2-4 
files, 3 
options, 3 
running, 3 
agetty, 1259-1262 
arguments, 1260 
bugs, 1261 
diagnostics, 1261 
files, 1261 
issue escapes, 1261 
options, 1260 
alarm, 744 
alarm clock, setting, 744 
alias (shell command), 35 
aliases, 23-24, 1106 
bugs, 1106 
printing, 35 
removing names, 45 
alloca function, 894 
bugs, 894 
return values, 894 
allocating memory, 894, 976 
allow-null_glob_ expansion 
variable (bash), 17 
allow-send-events( ) action 
(xterm), 714 


alphasort( ) function, 
1012-1013 
American Standard C ode for 
Information, see ASCII 
Andrew T oolkit raster objects, 
converting to portable 
bitmaps, 10 
ANSI C, converting to 
Kernighan & Ritchie, 4 
ansi2knr, 4 
antialiasing portable anymaps, 
381-382 
anytopnm, 4 
append (ftp command), 148 
application resources, 
printing, 5 
applications (client), listing, 
669-670 
appres, 5 
ar, 5-7 
copying, 7 
modifiers, 7 
options, 6-7 
arc cosines, 893 
arc sines, 894-895 
arc tangents, 896 
two variables, 896-897 
arch, 8 
archive, 1262-1263 
archives 
creating, 5-7 
extracting from, 5-7 
indexes (generating), 
437-438 
modifying, 5-7 
shell, creating, 484-487 
arguments 
concatenating, 37 
outputting, 36-37 
reading from standard input, 
586-587 
arithmetic 
evaluation 
bash, 34 
let command, 39 
expansion, bash, 20 


functions 
awk, 168-169 
gn( ), 1020-1021 
gnh( ), 1021 
grt( ), 1023 
tan( ), 1047-1048 
tanh( ), 1048 
performing on portable 
anymaps, 382-383 
arp, 1263 
ARP cache, manipulating, 
1263 
arrays 
awk, 164 
linear searches, 975-976 
searching sorted, 900-901 
sorting, 1000 
articles (news), see tin 
as, 8-9 
ASCII (American Standard 
Code for Information), 1064 
character set, 1214-1216 
graphics, converting to 
portable graymap, 10 
ascii (ftp command), 148 
ascii manual page, 1214-1216 
asciitopgm, 10 
asctime, 984-986 
asctime{ ) function, 910 
asin( ) function, 894-895 
errors, 895 
return value, 895 
asinh( ) function, 895 
assemblers, as, 8-9 
assert( ) function, 895-896 
asterisk (*), bash special 
parameters, 15 
at sign (@), bash special 
parameters, 15 
atan( ) function, 896 
atan2() function, 896-897 
atanh( ) function, 897 
Atari compressed Spectrum 
files, converting to portable 
pixmaps, 494 
Atari D egas P11 files, 
converting to portable 
pixmaps, 378 


awk 


Atari D egas P13 files, 
converting to portable 
bitmaps, 379 

Atari uncompressed Spectrum 
files, converting to portable 
pixmaps, 495-496 

atexit( ) function, 897-898 

errors, 898 

return value, 898 
atktopbm, 10 
atobm, 49-57 

options, 50 

atof( ) function, 898 

atoi( ) function, 898-899 

atol( ) function, 899 

attributes, file, 59 

authentication 

cidentd, 69-70 
Kerberos authentication, 
461 
pcnfsd, 1355-1356 
pppd, 1366-1367 
authority files (X), xauth 
utility, 587-592 
auto_resume variable (bash), 
18 

AutoCAD slide files, convert- 
ing to portable pixmaps, 
490-491 

AUTOSUBSCRIBE environ- 
ment variable, 529 

AUTOUNSUBSCRIBE 
environment variable, 530 

awk 

actions, 165-166 

arithmetic functions, 
168-169 

control statements, 167 

fields, 163 

functions, 170 

GNU extensions, 171 

historical features supported 
by gawk, 172 

1/O statements, 167 

operators, 166-167 

patterns, 165-166 

printf statement, 167-168 
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1436 


awk 


program execution, 162-163 
regular expressions, 166 
sprintf( ) function, 167-168 
string constants, 169-170 
string functions, 169 
time functions, 169 
variables, 163-165 

arrays, 164 

built-in, 163-164 

typing and converson, 

164-165 


backslashes (\), bash escape 
character, 14 
badblocks, 1264 
banner, 1210 
bash 
aliases, 23-24 
arguments, 11 
arithmetic evaluation, 34 
blanks, 12 
bugs, 46 
command execution, 25 
comments, 14 
compound commands, 13 
case, 13 
lig, 13 
while, 13 
control operators, 12 
environments, 25-26 
escape character, 14 
exit status, 26 
expansion, 18-21 
arithmetic, 20 
brace 19 
command subsitution, 20 
history, 33-34 
parameter, 19-20 
pathname, 21 
process ubstitution, 20 
quote removal, 21 
tilde 19 
word splitting, 21 
files, 46 
functions, 23 


history list, 32-33 
invocation, 45-46 
job control, 24-25 
lists, 12-13 
meta characters, 12 
names, 12 
options, 11 
parameters, 14-15 
postional, 14 
special, 14-15 
pipelines (|), 12 
prompting, 26 
quoting, 14 
readline, 27-32 
commands, 29-32 
controlling key bindings 
27 
customizing, 27 
denoting keystrokes, 27 
macro definitions 28 
parser directives 28-29 
variables, 28 
redirection, 21-23 
duplicating file descriptors 
23 
hee-documents, 22-23 
input, 22 
opening file descriptors 23 
operators, 21 
output, 22 
gandard error output, 22 
gandard output, 22 
reserved words, 12 
shell variables, 15-18 
allow- 
null_glob_ expangon, 17 
auto_reume, 18 
BASH, 15 
BASH_VERSION, 15 
cdable vars, 18 
CDPATH, 16 
command_oriented_hisory, 
17 
ENV, 16 
EVID, 15 
FCEDIT, 17 
FIGNORE, 17 


glob_dot_filevames 17 
histchars 17-18 
HISTCMD, 16 
HISTFILE, 17 
HISTFILESIZE, 17 
history control, 17 
HISTSIZE, 17 
HOME, 16 
hostname_compleion_file 
18 
HOSTTYPE, 16 
IFS, 16 
IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 
MAIL_WARNING, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_exit_on_failed_exer, 
18 
noclobber, 18 
nolinks, 18 
notify, 17 
OLDPWD, 15 
OPTARG, 16 
OPTERR, 17 
OPTIND, 16 
OSTYPE, 16 
PATH, 16 
PPID, 15 
PROMPT_COMMAND, 
17 
PS1, 16 
PS2, 16 
PS3, 17 
PS4,17 
PWD, 15 
RANDOM, 15 
REPLY, 15 
SECONDS, 15 
SHLVL, 15 
TMOUT,17 
UID, 15 
signals, 25 
simple commands, 12 
words, 12 


BASH variable (bash), 15 
BASH _VERSION variable 
(bash), 15 
bcmp( ) function, 899-901 
bcopy( ) function, 900-901 
BDF fonts, generating, 
146-147 
bdflush, 744-745 
errors, 745 
return value, 745 
bdftopcf, 47 
beforelight, 47-48 
bell (ftp command), 148 
bell( ) action (xterm), 713 
bell-style variable (readline), 
28 
Bennet Yee face files, see face 
files 
Bentleyizing portable 
graymaps, 369 
Bessel functions, 959-960 
jO( ), 959 
j1(), 959 
jn(), 959 
y0( ), 959 
y1( ), 959 
yn( ), 959 
bg (shell command), 35 
bibliographic databases, 219 
fidds, 219 
inverted indexes, 209-210 
searching, 210, 292-293 
biff, 48 
biff server, 1274-1275 
/bin directory, 1236 
binary (ftp command), 148 
binary dates/times, converting 
to ASCII, 909-911 
binary files, encoding/ 
decoding, 565-566 
binary streams, input/output 
(getting), 926-927 
binary trees 
ddeting items, 1056 
searching, 1056 
traversing, 1056 


bind, 35, 745-746 
errors, 745-746 
return value, 745 
binding names to sockets, 
745-746 
bioradtopgm, 48-49 
bugs, 49 
options, 49 
bit sets, finding first in words, 
921 
Bitmap Distribution Format 
fonts, converting to Portable 
Complied Format, 47 
bitmap widget, 56-57 
bitmaps, 49-57 
CMU, converting to 
portable, 71 
color, 56 
conversion, 49 
cutting and pasting, 54 
display, 50 
drawing commands, 51-53 
Edit menu commands, 
53-54 
editing images, 50-51 
File menu commands, 53 
options, 49-50 
Universal Product Code, 
creating, 368 
widgets, 54-56 
blanks (bash), 12 
block buffered streams, 1016 
block special files, creating, 
325 
BMP files, converting to 
portable pixmaps, 57 
bmptoppm, 57 
bmtoa, 49-57 
/boot directory, 1236 
boot-time parameters 
(kernel), see bootparam 
bootparam, 1216-1224 
Adaptec configurations, 
1219-1220 
argument list, 1216-1217 
Bus ogic configuration, 
1220 


bsearch( ) function 


busmouse driver parameters, 
1224 
CD-ROM parameters, 
1222-1223 
debug argument, 1217 
Ethernet device parameters, 
1223 
floppy disk driver param- 
eters, 1223-1224 
future domain configura- 
tion, 1220 
hard disk parameters, 
1220-1221 
men=argument, 1218 
no-hit argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 
ramdisk= argument, 1218 
reboot=warm argument, 
1218 
reserve= argument, 
1217-1218 
ro argument, 1217 
root=argument, 1217 
rw argument, 1217 
SCSI device arguments, 
1218-1219 
SCSI tape configuration, 
1219 
Seagate ST -0x configuration, 
1220 
sound driver parameters, 
1224 
Trantor T 128 configuration, 
1220 
Bourne shell, see sh 
Bourne-again shell, see bash 
brace expansion, 19 
break (shell command), 35 
brk, 746 
browsers, lynx, 306-309 
commands, 308-309 
options, 306-308 
brushtopbm, 57 
bsearch( ) function, 900-901 
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buffchan 


buffchan, 1264-1265 
drop command, 1265 
flush command, 1265 
readmap command, 1265 
buffer-dirty-flush daemon, 
744-745 
buffering streams, 1016-1017 
buffers 
cache, committing to disk, 
869 
filesystem, flushing, 
1401-1402 
flushing from files to disk, 
756-757 
kernd log, 873 
kernel message ring, reading/ 
clearing, 872-874 
multiple, reading/writing 
data, 1003-1004 
BUG ADDRESS environ- 
ment variable, 529 
buildhash, 274, 279 
files, 281 
builtin (shell command), 35 
busmouse drivers, boot-time 
parameters, 1224 
bye (ftp command), 148 
byte strings 
comparing, 899-900 
copying, 900 
operations, 901 
writing zeros to, 902 
bytes 
counting (in files), 70 
swapping adjacent, 1043 
bzero( ) function, 901-902 


C 


C 
converting AN SI to 
Kernighan & Ritchie, 4 
functions, displaying 
headers, 455-456 
preprocessors, 81-84 
imake 264-267 
options 82-84 


string table source files/ 
headers, 314-315 
ge als gcc 
C++ compiler, see g++ 
cacheflush, 746-747 
bugs, 747 
errors, 747 
return value, 747 
caches (ARP), manipulating, 
1263 
CAclose routine, 964 
cal, 58 
calendar sheets, see gcal 
CAlistopen routine, 964 
calling up systems, 88-90 
calloc( ) function, 976 
canonicalized absolute 
pathnames, 1004-1005 
CAopen routine, 964 
case 
bash command, 13 
ftp command, 148 
cat, 58-59 
catclose( ) function, 903-904 
catgets( ) function, 902-903 
catopen( ) function, 903-904 
cccp, 81-84 
copying, 84 
options, 82-84 
cd 
ftp command, 148 
shell command, 35-36 
CD-ROMs, boot-time 
parameters, 1222-1223 
cdable_vars variable (bash), 
18 
CDPATH variable (bash), 16 
cdtin, 516 
ge als tin 
cdup (ftp command), 148 
ceil( ) function, 904 
cfdisk, 1265-1269 
bugs, 1269 
commands, 1267-1268 
options, 1268-1269 
cfgetispeed( ) function, 877, 
1053 


cfgetospeed( ) function, 877, 
1052 
cfingerd, 1106-1109 
bugs, 1108 
error messages, 1108 
features, 1107-1108 
options, 1106-1107 
SYSLOG messages, 1108 
text commands, 1115 
cfingerd.conf, 1109-1115 
display files section, 
1109-1110 
finger display configure 
section, 1110-1111 
finger fake users files section, 
1114 
finger programs files section, 
1114 
finger strings configure 
section, 1113 
forwarded host section, 
1112 
internal config configure 
section, 1111-1112 
internal strings configure 
section, 1113 
rejected host section, 1112 
services header configure 
section, 1114 
services positions configure 
section, 1114-1115 
signal strings configure 
section, 1113-1114 
system list sites configure 
section, 1112 
trusted host section, 1112 
cfmakeraw( ) function, 1052 
cfsetispeed( ) function, 877, 
1053 
cfsetospeed( ) function, 877, 
1052-1053 
character sets, 1064-1066 
ASCII, 1064, 1214-1216 
ISO 2022, 1066 
ISO 4873, 1066 
ISO 8859, 1064-1065 
ISO 8859-1, 1239-1242 
alphabets, 1240 
characters, 1240-1242 


KO18-R, 1065 
Unicode, 1065, 1253-1255 
combining characters, 
1254 
implementation levds, 
1254 
character special files, 
creating, 325 
characters 
classifying, 957-958 
converting 
to ASCII, 1055 
wideto multibyte, 
1061-1062 
locating in strings, 953, 
1029 
multibyte, converting to 
wide characters, 978 
outputting, 997-999 
returning number of bytes 
in, 977 
searching strings for sets, 
1035-1039 
translating/deleting, 
536-539 
chat, 727-730, 1269-1273 
abort strings, 1270-1271 
Boolean options, 729 
daemons, 727 
escape menu, 728 
escape sequences, 
1271-1272 
options, 1269-1270 
readdressing, 729 
report strings, 1271 
runtime options, 728-729 
script, 1270 
startup file 729 
termination codes, 1272 
timeout value 1271 
username field, 727 
X11 interface, 730 
chattr, 59-60 
chdir, 747-748 
checkout (cvs command), 
96-97 
checksums, computing on 
files, 501 


chfn, 60 
chgrp, 61 
child processes, creating, 751, 
758 
chkdupexe, 61 
chmod, 61-62, 148, 748-749 
errors, 749 
operators, 62 
options, 62 
return value, 748 
specifying mode, 748 
chooser (xdm), 607 
chown, 62-63, 749-750 
errors, 749-750 
options, 63 
chroot, 750-751, 1273 
errors, 750-751 
return value, 750 
chsh, 63 
ci, 64-69 
controlling file access, 67 
diagnostics, 68 
environment, 68 
file modes, 67 
options, 65-66 
setuid privileges, 67-68 
specifying files, 66-67 
temporary files, 67 
cidentd, 69-70 
cksum, 70 
clear, 70-71 
clear-saved-lines( ) action 
(xterm), 715 
clearerr function, 919-920 
clearing terminal screen, 
70-71 
clientlib, 904-905 
clients 
listing running applications, 
669-670 
Remote Start, se rstart 
X, killing, 666-667 
clipboards, X client, 595-597 
buttons, 596 
sending/retrieving contents, 
596-597 


commands 


clock, 344, 1273-1274 
colors, 344 
options, 1273 
xclock, 593-595 
clock( ) function, 905 
clocks 
alarm, setting, 744 
CMOS, 1273-1274 
kernel, adjusting, 742-743 
clone, 751 
close, 752 
ftp command, 148 
telnet command, 508 
closedir( ) function, 905-906 
closelog( ) function, 
1045-1046 
CloseO nExec routine, 965 
CMOS clock, 1273-1274 
CMU bitmaps, converting to 
portable, 71 
cmuwmtopbm, 71 
co, 71-75 
diagnostics, 75 
environment, 75 
file modes, 75 
keyword substitution, 74-75 
limitations, 75 
options, 72-74 
col, 76 
colcrt, 77 
color, bitmap application, 56 
colrm, 77-78 
column, 78 
columns 
formatting lists into, 78 
removing from files, 77-78 
comm, 78-79 
options, 79 
command (shell command), 
36 
command-line options, 
parsing, 937-940 
command_oriented_history 
variable (bash), 17 
commands 
bitmap application 
drawing, 51-53 
Edit menu, 53-54 
Filemenu, 53 
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commands 


building/executing from 
standard input, 586-587 
cu, 88-89 
cvs, 91-104 
editres, 121-122 
execution, bash, 25 
exit status, 26 
ftp, 148-152 
gpic, 212-213 
history lists, displaying, 39 
info, 269-270 
ispal, 274-275 
locating source/binary and 
manuals files, 575-576 
Ipc, 1317-1318 
lynx, 308-309 
more, 328 
nslookup, 1351-1353 
options, parsing, 207-208 
RCS, 447-449 
readline library, 29-32 
redirection, 21-23 
duplicating file descriptors 
23 
hee-documents, 22-23 
input, 22 
opaing file descriptors 23 
operators, 21 
output, 22 
gandard error output, 22 
gandard output, 22 
remote execution, 569-571 
sed, 478-479 
grouping, 478 
gyntax, 476 
shell (built-in), 35-45 
enabling/disabling, 37 
hdp information, 38 
telnet, 508-512 
tftp, 514 
timedc, 1409 
tin 
article viewer, 522-524 
editing, 519 
global options menu, 524- 
525 
group index, 521-522 


newsgroup selection, 
519-520 
spool directory ection, 
520 
thread listing, 522 
top, 534-535 
xauth, 588, 591 
zmore, 733-734 
comment-begin variable 
(readline), 28 
comments 
bash, 14 
sed, 477 
commit (cvs command), 
96-98 
comparing 
files, 78-79 
compressed, 731-732 
strings, 1029-1030 
ignoring caw, 1028 
using current locale 1030 
compilers 
gH, 155-160, 174-201 
bugs 160 
copying, 160, 201 
filename suffixes 174-175 
files, 159-160, 200 
options, 155-159, 
175-178 
pragmas 159, 200 
gcc, 174-201 
asembling output, 8-9 
bugs 201 
copying, 201 
filename suffixes 174-175 
files, 200 
options, 175-178 
pragmas 200 
rpcgen, 464-466 
compiling, make utility 
(recompiling programs), 
310-312 
completion-query-items 
variable (readline), 28 
compound commands (bash), 
13 


compressed files 
comparing, 731-732 
compressing/expanding, 
248-252 
executable files, 252-253 
searching for regular 
expressions, 733 
viewing text, 733-734 
comsat, 1274-1275 
concatenating 
files, 58-59 
compressed, 251 
portable anymaps, 383 
strings, 1028-1029 
Concurrent Versions System, 
see CVS 
conditional expressions, 
evaluating, 43 
configurable finger daemon, 
1106-1109 
configuration file, 
1109-1115 
display files section, 
1109-1110 
finger display configure 
gction, 1110-1111 
finger fake uss files 
section, 1114 
finger programs files 
section, 1114 
finger strings configure 
gction, 1113 
forwarded host section, 
1112 
internal config configure 
gction, 1111-1112 
internal strings configure 
gction, 1113 
rejected host section, 1112 
services header configure 
section, 1114 
gervices postions configure 
gction, 1114-1115 
ggnal strings configure 
gction, 1113-1114 
gysten list Stes configure 
gction, 1112 
trusted hos section, 1112 





error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 
configuration information, 
getting at runtime, 
1043-1045 
configuring 
network interfaces, 
1304-1305 
rstartd, 469 
keywords, 470 
serial ports, 1394-1395 
SF86_SVGA servers, 
627-628 
SF86_VGA16 servers, 631 
system logging file, 
1402-1403 
tinrc, 525-526 
XF86_Accel servers, 
615-616 
XF86_M ono servers, 624 
XFree86, 636 
xfs, 642 
xinetd, 656-660 
confstr( ) function, 906-907 
connect, 752-753 
connections 
dialup IP, handler, 
1285-1288 
displaying active, 1339-1342 
routing information, 1341 
socket information, 
1340-1341 
displaying active routing 
information, 1341 
full-duplex, shutting down, 
855 
socket 
accepting, 740-741 
initiating, 752-753 
listening for, 792-793 
console, 1066-1067 
console_codes, 1067-1074 
character sets, 1072 
control characters, 1068 
CSI sequences, 1069-1070, 
1074 


display attributes, 
1070-1071 
ESC sequences, 1068-1069, 
1073-1074 
mode switches, 1071 
mouse tracking, 1072-1073 
private CSI sequences, 1072 
Set/Reset M ode sequences, 
1071 
status report commands, 
1071 
console _ioctls, 1074-1080 
consoles 
control-character handling, 
1073 
properties, 1067 
sequences, 1067-1074 
character sets, 1072 
control characters, 1068 
CSI, 1069-1070, 1074 
display attributes, 
1070-1071 
ESC, 1068-1069, 
1073-1074 
mode switches 1071 
mouse tracking, 
1072-1073 
privateC SI, 1072 
Sd&/Res& M ode 1071 
gatus report commands, 
1071 
starting processes on, 1066 
switching, 1067 
virtual, 1066 
memory, 1101-1102 
continue (shell command), 36 
control messages, 1310 
control operators (bash), 12 
control statements, awk, 167 
control.ctl, 1115-1116 
controlling terminal, getting 
name, 909 
convdate, 79 
conversational exchanges, 
1269-1273 
abort strings, 1270-1271 
chat script, 1270 
escape sequences, 
1271-1272 


converting 


report strings, 1271 
termination codes, 1272 
timeout value 1271 
convert-meta variable 
(readline), 28 
converting 
Abekas YU V bytes to 
portable pixmaps, 731 
Andrew T oolkit raster 
objects to portable 
bitmaps, 10 
ANSI C to Kernighan & 
RitchieC, 4 
ASCII graphics to portable 
graymap, 10 
Atari files 
compressed Spectrum files 
to portable pixmaps, 494 
D egasP!1 filesto portable 
pixmaps, 378 
D egasP|3 filesto portable 
bitmaps 379 
uncompressed Spectrum 
files to portable pixmaps, 
495-496 
AutoCAD slide files to 
portable pixmaps, 490-491 
Bennet Yee face files to 
portable bitmaps, 726 
Biorad confocal files to 
portable graymaps, 48-49 
bitmap files, 49 
CMU to portable 71 
to portable pixmaps, 57 
characters 
to ASCII, 1055 
wideto multibyte 
1061-1062 
dates/times, 79 
to ASCII, 984-986 
to Discordian format, 
1210-1211 
documents, troff to LaT eX, 
1252-1253 
doodle brush files to 
portable bitmaps, 57 
FITS files to portable 
anymaps, 142-143 
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fonts 
Bitmap D isribution 
Format to Portable 
Compiled Format, 47 
packed format to portable 
bitmaps 381 
GEM IMG files to portable 
bitmaps, 201 
GIF files to portable 
anymaps, 208-209 
Gould scanner files to 
portable pixmaps, 211 
groff output to T eX dvi 
format, 227-228 
Group 3 fax files to portable 
bitmaps, 160-161 
HIPS files to portable 
graymaps, 256 
H P Paint et files to portable 
pixmaps, 381 
ILBM files to portable 
pixmaps, 263-264 
image file to portable 
anymap, 4 
Img-whatnot files to 
portable pixmaps, 267 
letters 
to lowercase 1055-1056 
to uppercase, 1055-1056 
Lisp machine bitmap files to 
portable graymaps, 292 
Macintosh PICT files to 
portable pixmaps, 379-380 
M acPaint files to portable 
bitmaps, 309-310 
MGR bitmaps to portable 
bitmaps, 322-323 
multibyte characters to wide 
characters, 978 
multibyte strings to wide 
character, 977-978 
object codeinto NLM 
outfiles, 338-339 
PCX files to portable 
pixmaps, 368-369 
Photo-CD files to portable 
pixmaps, 260-261 


portable anymaps 

to DDIF format, 396 

to FITS format, 396-397 

to PostScript, 397 

to SGI imagefile 
398-399 

to Solitaire format, 399 

to Sun rager files, 398 

to TIFF files, 399-400 

into X11 window dumps, 
400 

portable bitmaps 

to Andrew T oolkit raster 
objects 358 

to ASCII graphics, 357 

to Atari D egas P| 3 files, 
364 

to Bennet Y ee “face’ files 
367 

to BitGraph graphics 358 

to CMU window manager 
bitmaps 358-359 

to compressed GraphO n 
graphics 360-361 

to DEC LN 03+ Sixd 
output, 362 

to encapsulated PosScript- 
gyle bitmaps, 359 

to Epson printer graphics, 
359 

toGEM IMG files, 360 

to Gemini 10x graphics, 
356 

to Group 3 fax files 360 

to HP Lasy] & format, 
361-362 

to M acPaint files 363 

to MGR bitmap, 363 

to packed format fonts, 
364-365 

to portable graymaps, 364 

to PostScript, 362 

to Printronix printer 
graphics 366 

to Sun icons, 361 

to UNIX plot file, 
365-366 


to X10 bitmaps 366 
to X11 bitmaps 367 
to Zinc bitmaps 367-368 
portable graymaps 
to Lisp machine format, 
376-377 
to portable bitmaps 377 
to portable pixmaps, 378 
to U senix FaceSaver 
format, 376 
portable pixmaps 
to Abas YU V files, 428 
to Atari D egas P11 files, 
422 
to AutoCAD, 414-416 
to BMP files, 416 
to DEC sxe format, 
425-426 
to GIF files 416-417 
toH P Paintje file, 423 
toHP Paintje XL PCL 
files, 424 
tolLBM files 418-419 
to Macintosh PICT files, 
422-423 
0 Mitsubishi 340-10 
file, 420-421 
0 MotifU IL icon files, 
427 
o NCSA ICR format, 
417-418 
to PCX files 421 
to portable graymaps, 
421-422 
to red/blue 3D glasses, 
400-401 
to three portable graymaps, 
425 
to three raw YU V files, 
428-429 
to TrueVision T arga files, 
426 
to X11 pixmaps 427-428 
to X11 puzzle file, 
424-425 
PostScript files to portable 
anymaps, 434-435 


ot 


ot 





ot 


PostScript image data to 
portable graymap, 
433-434 

QRT ray tracer output to 
portable pixmaps, 436-437 

raw grayscale bytes to 
portable graymaps, 439 

raw RGB bytes to portable 
pixmaps, 439-440 

ray tracer output to portable 
pixmaps, 333 

SGI image files to portable 
anymaps, 483-484 

Solitaire files to portable 
anymaps, 488-489 

spaces to tabs, 559 

SPOT satellite images to 
portable graymaps, 495 


strings 
ASCII to double 
1039-1040 


to long integers 1041 
to ung gned long integers, 
1041-1042 
wide character to 
multibyte character, 
1061 
Sun icons to portable 
bitmaps, 262 
Sun raster files to portable 
anymaps, 438 
tabs to spaces, 137 
TIFF files to portable 
anymaps, 515-516 
times 
initializing information, 
1058-1060 
to ASCII, 984-986 
to tm structure 1036- 
1037 
T rueVision T arga files to 
portable pixmaps, 515 
Usenet batch files to IN N 
format, 1281-1282 
U senix FaceSaver files to 
portable graymaps, 147 


X11 or X10 bitmaps to 
portable, 592 
X11 pixmaps to portable 
677 
X11/X10 window dump 
files to portable anymaps, 
722 
X config file format to 
XF86C onfig, 454 
XIM files to portable 
pixmaps, 654 
XV thumbnail pictures to 
portable pixmaps, 720 
YUV files to portable 
pixmaps, 730-731 
convolution kernels, generat- 
ing, 372-373 
cookies, generating, 317 
copying 
ar utility, 7 
as, 9 
byte strings, 900 
files, 80-81 
converting while 108-109 
incall, 272-273 
MS-DOS to/from UNIX, 
317-318 
UNIX-to-U NIX, 
563-565 
MS-DOS files to UNIX, 
329 
number signs, 907 
strings, 1030-1031 
gpcpy( ) function, 
1027-1028 
copysign( ) function, 907 
cos( ) function, 907 
cosh( ) function, 908 
cosines, 907 
cp, 80-81 
cpp, 81-84 
copying, 84 
options, 82-84 
CPU, listing most intensive 
processes, 533-535 
cr (ftp command), 148 
creat, 815-816 


CVS 


create_module, 800-802 
crond, 1275 
crontab, 84-85 
crypt function, 908-909 
csplit, 85-86 
ctags, 87-88, 135-137 
bugs, 88 
copying, 136-137 
files, 87 
options, 87, 136 
ctermid( ) function, 909 
ctime, 909-910, 984-986 
ctlinnd, 1276-1279 
bugs, 1279 
commands, 1276-1278 
Ctrl+Alt+D ea combination, 
setting function, 1279 
ctri_alt_dedl, 1425 
ctrlaltdel, 1279 
cu, 88-90 
bugs, 90 
commands, 88-89 
options, 89-90 
cuserid( ) function, 934-935 
bugs, 935 
errors, 934 
files, 935 
cut, 90-91 
cut buffers, copying selections 
into, 598-599 
cvs, 91-106, 1116-1120 
commands, 91-104 
add, 96 
admin, 96 
checkout, 96-97 
commit, 96-98 
diff, 98 
export, 98 
history, 99 
import, 100 
log, 100 
rdiff, 101 
release 101 
remove, 101-102 
rtag, 102 
gatus, 102 
tag, 102-103 
update 103-104 
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environment variables, 
105-106 
CVS IGNORE_REMOTE 
_ROOT, 105 
CVS_RSH, 106 
CVS SERVER, 106 
CVSEDITOR, 105 
CVSREAD, 105 
CVSROOT, 105 
CVSWRAPPERS, 106 
RCSBIN, 105 
files, 104-105, 1117-1119 
options, 92-104 
checkout command, 97 
commit command, 97 
history command, 99 
import command, 100 
rdiff command, 101 
sending problem reports, 
1279-1281 
filling out reports 
1280-1281 
startup file 93 
support files, 1116-1120 
CVS_IGNORE_REMOTE 
_ROOT environment 
variable, 105 
CVS_RSH environment 
variable, 106 
CVS_SERVER environment 
variable, 106 
cvsbug, 1279-1281 
EMACS interface, 1281 
environment, 1280 
files, 1281 
filling out reports, 
1280-1281 
options, 1280 
CVSEDITOR environment 
variable, 105 
CVSREAD environment 
variable, 105 
CVSROOT environment 
variable, 105 
CVSW RAPPERS environment 
variable, 106 


cvtbatch, 1281-1282 
Cyclades drivers, tuning, 
1282-1284 
cytune, 1282-1284 
bugs, 1283 
options, 1283 


D 


daemons 
buffer-dirty-flush, 744-745 
configurable finger daemon, 
1106-1109 
configuration file 
1109-1115 
error mesages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 
cron, 1275 
InterN etN ews, 1309-1312 
control messages 1310 
controling, 1276-1279 
kernel log, 1315-1317 
line printer spooler, 
1318-1320 
network routing, 1380-1382 
NFS mount, 1332-1333 
NFS service, 1347 
powerd, 1359-1360 
pppd, 1360-1369 
time server, 1407-1408 
UUCP file transfer, 
1415-1417 
DARPA 
FT P server, 1301-1304 
requests supported, 
1302-1303 
port numbers, converting 
PRC program numbers to, 
1358-1359 
T dnet server, 1406-1407 
TFTP server, 1407 
data buffers, flushing from 
files to disk, 756-757 
data cache, flushing contents, 
746-747 
data segments, changing, 746 


databases 
bibliographic, 219 
fidds 219 
inverted indexes, 209-210 
gar ching, 210, 292-293 
filerame, updating, 561-562 
files, searching for patterns, 
295 
news overview 
expiring entries 
1293-1294 
format, 1168-1169 
updating, 1353-1354 
ps, updating, 436 
rebuilding for mail aliases 
file 336 
RGB colorname 
uncompiling, 488 
terminal capability, 
1188-1197 
boolean capabilities 1189 
numeric capabilities, 
1189-1190 
gring capabilities 
1190-1197 
Usenet, recovering, 1342- 
1344 
date, 106-108 
arguments, 106-107 
files, 108 
options, 108 
dates/times 
converting, 79 
to ASCII, 909-911, 
984-986 
to Discordian format, 
1210-1211 
grings to numbers, 
989-990 
formatting, strftime( ) 
function, 1032-1034 
returning current, 928-929 
setting, 107-108 
showing, 106-107 
dd, 108-109 
ddate, 1210-1211 
D D check routine, 965 


DDend routine, 965 
D Dstart routine, 965 
debug (ftp command), 149 
debugfs, 1284-1285 
commands, 1284-1285 
options, 1284 
declare (shell command), 36 
del_timer, 1424 
delete_ module, 800-802 
delete (ftp command), 148 
deleting 
binary tree items, 1056 
directories, 829-830 
MS-DOS directory trees, 
319 
MS-DOS files, 318-319 
depmod, 109-112 
configuration, 110-111 
files, 111 
strategy, 111 
descriptor tables, size 
(getting), 760-761 
descriptors, testing, 958-959 
/dev directory, 1236 
devices 
bad blocks (searching for), 
1264 
controlling, 774-788 
ioctl calls (list of), 
775-786 
creating, 815-816, 
1321-1324 
describing all, 1120-1121 
disk, ram, 1094-1095 
DOS (table of), 1152-1158 
Ethernet, boot-time 
parameters, 1223 
floppy disk, 1080-1083 
configuration, 1080-1082 
hard disk, 1083 
line printer (ioctl( ) calls), 
1090-1091 
lp, parameters (setting), 
1413-1414 
opening, 815-816 
PLIP, tuning parameters, 
1357 


SCSI tape, drivers, 
1096-1100 
setup, 849 
swapping 
@abling/disabling, 1401 
garting/topping, 866-867 
terminal (list of), 1197 
DEVINFO, 1120-1121 
df, 112-113 
dialup IP connection handler, 
1285-1288 
dialin mode, 1286-1287 
dialout mode, 1287-1288 
dictionaries, compressing/ 
uncompressing, 496 
diff (cvs command), 98 
difftime, 911, 984-986 
dig, 113-117 
bugs, 117 
environment, 117 
files, 117 
options, 114-115 
dip, 1285-1288 
command mode, 1285-1286 
dialin mode, 1286-1287 
dialout mode, 1287-1288 
files, 1288 
dir, 303-304 
bugs, 304 
ftp command, 149 
options, 303-304 
directories 
/, 1236 
adding to stack, 40 
alphabetizing entries, 
1012-1013 
/bin, 1236 
/boot, 1236 
changing, 35-36, 747-748 
closing, 905-906 
creating, 323 
mkdir, 794-795 
mknod, 795-796 
deleting, 829-830 
/dev, 1236 
displaying list of, 36 
/dos, 1236 


directory trees 


/etc, 1236 
/etc/skel, 1236 
/etc/X11, 1236 
files (searching for), 137-142 
getting current, 931 
getting entries, 759 
fil esystem- independent 
format, 931-932 
hierarchies, creating, 323 
/home, 1236 
/lib, 1236 
listing contents, 303-304 
/mnt, 1236 
MS-DOS 
changing, 316-317 
displaying, 319 
opening, opendir, 989 
printing pathnames, 40 
/proc, 1236 
promoting, 39-40 
RCS, creating, 447-449 
reading 
entries 823 
readdir( ) function, 
1002-1003 
removing, 462 
root, changing, 750-751, 
1273 
/sbin, 1237 
scanning for matching 
entries, 1012-1013 
stream, resetting, 1011 
/tmp, 1237 
trees, walking through, 930 
/usr, 1237 
/usr/X11R6, 1237 
/usr/X11R6/bin, 1237 
/usr/X11R6/lib, 1237 
/usr/X11R6/lib/X11, 1237 
/usrX11R6/include/X 11, 
1237 
directory stream, current 
location (returning), 1048 
directory trees 
MS-DOS, deleting, 319 
shadow directories 
(creating), 294 
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dirs (shell command), 36 
disconnect (ftp command), 
149 
Discordian dates (converting 
to), 1210-1211 
disks 
adding M S-D OS filesystems 
to, 321-322 
devices, ram, 1094-1095 
displaying usage/limits, 437 
floppy 
formatting, 1295-1296 
marking bad blocks, 316 
stting parameters, 1391 
MS-DOS, mounting, 
326-327 
quotas, manipulating, 
821-822 
SCSI, drivers, 1095-1096 
summarizing free space, 
112-113 
summarizing usage, 120-121 
Xdf, 332 
display argument command 
(telnet), 508 
DISTRIBUTION environ- 
ment variable, 529 
div( ) function, 911 
dividing integers, 911 
floating-point remainders, 
913, 923 
returning quotient and 
renainder, 961 
dmesg, 1288-1289 
dn_comp, 1008-1011 
dn_expand, 1008-1011 
dnsdomainname, 259-260 
dnsquery, 117-119 
bugs, 119 
diagnostics, 118 
files, 118 
options, 117-118 
documents 
converting, troff to LaT eX, 
1252-1253 
formatting, gtroff, 237-248 


dollar signs ($) 
bash special parameters, 15 
expansion, 19 
ftp command, 148 
domain names 
current host, 119 
displaying, 259-260 
getting/setting, 760 
querying servers, 117-119 
sending query packets to 
servers, 113-117 
servers, resolver routines, 
1008-1011 
domain servers, looking up 
hostnames with, 257-258 
domainname, 119 
domains, nameserver, 
1334-1338 
querying, 1350-1353 
doodle brush files, converting 
to portable bitmaps, 57 
DOS devices, table of, 
1152-1158 
/dos directory, 1236 
drand48( ) functions, 912 
drawing bitmaps (commands), 
51-53 
drem( ) function, 913 
drivers 
busmouse, boot-time 
parameters, 1224 
Cyclades, tuning, 
1282-1284 
floppy disk, boot-time 
parameters, 1223-1224 
SCSI disks, 1095-1096 
SCSI tape devices, 
1096-1100 
ioctl( ) calls 1097-1100 
sound, boot-time param- 
eters, 1224 
dsplit, 119-120 
du, 120-121 
dumpe2fs, 1289 
dumping files, 345-346 
dup, 753-754 


dup2, 753-754 

duplicate executables, finding, 
61 

duplicating strings, 1031 


email 
notification, 48 
sending, 1387-1390 
aliases, 1390 
e2fsck, 1289-1291 
bugs, 1291 
exit code, 1290 
options, 1290 
echo (shell command), 36-37 
ECHO_REQUEST packets, 
sending, 1358 
ecvt( ) function, 913-914 
Edit menu commands, bitmap 
application, 53-54 
editing bitmaps, 49-51 
editing-mode variable 
(readline), 28 
editors 
emacs, 130-133 
bugs 133 
distributing, 133 
files, 132-133 
manuals, 132 
mouse button bindings 
132 
options, 130 
X Window Systen, 
131-132 
stream-oriented, see sed 
editres, 121-126 
beginning sessions, 121 
blocking requests, 124 
commands, 121-122 
environment, 126 
files, 126 
options, 121 
resource box, 123-124 
resources, 124-125 
widgets, 125-126 
window, 121 


edquota, 1291-1292 
egrep, 224-226 
bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 
$ese parser directive 
(readline), 29 
elvis, 126-128 
bugs, 128 
environment, 127-128 
files, 127 
options, 127 
ref interaction, 455 
tag files, 135-137 
elvprsv, 128-129 
elvrec, 129-130 
emacs, 130-133 
bugs, 133 
distributing, 133 
files, 132-133 
function key/mouse support, 
134-135 
manuals, 132 
mouse button bindings, 132 
options, 130 
tag files, 135-137 
using emacstool with, 135 
X Window System, 131-132 
EMACS user interface, 
cvsbug, 1281 
emacstool, 134-135 
bugs, 135 
environment variables, 135 
files, 135 
options, 134 
using with emacs, 135 
enable (shell command), 37 
encoded files, uuencode 
format, 1200 
encryption 
crypt function, 908-909 
memory areas, 980-981 
endgrent( ) function, 932-933 
$endif parser directive 
(readline), 29 


endmntent( ) function, 
935-936 
endnetent subroutine, 
936-937 
endprotoent( ) function, 
941-942 
endpwent( ) function, 943 
endservent( ) function, 946 
endusershell( ) function, 
946-947 
endutent( ) function, 947 
ENV variable (bash), 16 
environ, 1121 
environ command (telnet), 
511 
environment variables 
adding/changing, 996-997, 
1017 
bash, 25-26 
ci, 68 
co, 75 
cvs, 105-106 
CVS IGNORE 
_REMOTE_ROOT, 
105 
CVS_RSH, 106 
CVS SERVER, 106 
CVSEDITOR, 105 
CVSREAD, 105 
CVSROOT, 105 
CVSWRAPPERS, 106 
RCSBIN, 105 
cvsbug, 1280 
dig, 117 
editres, 126 
avis, 127-128 
emacstool, 135 
fsinfo, 145 
fslsfonts, 146 
fstobdf, 146 
ftp, 154 
gawk, 172 
getopt( ) function, 939 
getting, 932 
groff, 229 
gtroff, 248 
gzip, 251 


environment variables 


imake, 267 

info, 270 

Id, 291 

Ikbib, 293 

locate, 295 

Ipq, 299 

Ipr, 300 

lprm, 302 

more, 328 

nslookup, 1353 

rcs, 443 

resclean, 444 

rcsdiff, 445 

rcsmerge, 450 

ref, 455 

rlog, 459 

rlogin, 461 

script, 475 

startx, 497 

tcal, 506 

telnet, 512 

tin, 528-530 
ADD_ADDRESS, 529 
AUTOSUBSCRIBE, 529 
AUTOUN SUBSCRIBE, 

530 

BUG_ADDRESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
NNTPSERVER, 529 
ORGANIZATION, 529 
REPLYTO, 529 
TI_ACTIVEFILE, 529 
TI_LNOVROOTDIR, 529 
TIN_HOMEDIR, 528 
TIN_INDEXDIR, 529 
TIN_LIBDIR, 529 
TIN_SPOOLDIR, 529 
TINRC, 528 
VISUAL, 529 

tset, 541 

twm, 557 

TZ, 987 

ul, 559 

xauth, 589, 592 

xclipboard, 597 

xclock, 595 

xcmsdb, 593 


1447 


1448 


environment variables 


xconsole, 598 
xdm, 608 
XFree86, 637 
xhost, 644 
xinit, 666 
xlogo, 668 
xlsatoms, 669 
xIsclients, 669 
xlsfonts, 671 
xmodmap, 675 
xprop, 680 
xrdb, 684 
xrefresh, 685 
xstdcmap, 700 
xterm, 717 
xwd, 722 
xwininfo, 724 
xwud, 726 
eqn, see geqn 
equation formatting, 202-206 
erand48( ) functions, 912 
erf( ) function, 914 
erfc( ) function, 914 
errno, 916-917 
error functions, 914 
errors 
access, 741 
adjtimex, 743 
bdflush, 745 
bind, 745-746 
cacheflush, 747 
chdir/fchdir, 747-748 
chmod, 749 
chown, 749-750 
chroot, 750-751 
clone, 751 
close, 752 
codes, describing (returning 
strings), 1032 
creat, 816 
dup/dup2, 753 
execve, 754 
fchmod, 749 
fchown, 749-750 
fentl, 756 
fdatasync, 757 
fork/vfork, 758 


fsync, 759 
getdents, 759 
getdomainname, 760 
getgroups, 762 
gethostname, 763 
getitimer, 764 
getpeername, 765 
getpriority, 766-767 
getrlimit, 768 
getsid, 768 
getsockname, 769 
getsockopt, 771 
gettimeofday, 773 
idle, 774 

ioctl, 774 

iopl, 789 

kill, 790 

killpg, 791 

link, 791-792 
listen, 792 

Ilseek, 793 

Iseek, 794 

mkdir, 795 
mknod, 796 
mlockall, 798 
mmap, 799 
modify_Idt, 800 
mount, 803 
mprotect, 804 
mremap, 806 
msgctl, 807 
msgget, 808 
msgop, 810 
munlock, 812 
munmap, 799 
mysnc, 811 
nanosleep, 813 
nice, 814 

open, 816 

pause, 817 
personality, 818 
return value, 797 
returning number, 916-917 
setdomainname, 760 
setgroups, 762 
sethostname, 763 
setitimer, 764 


setpriority, 766-767 
setrlimit, 768 
setsockopt, 771 
settimeofday, 773 
symbolic error names, 
916-917 
unmount, 803 
escape character, bash, 14 
etags, 135-137 
copying, 136-137 
options, 136 
/etc directory, 1236 
/etc/modules file, 1152 
/etc/skel directory, 1236 
/etc/X11 directory, 1236 
Ethernet devices, boot-time 
parameters, 1223 
Euclidean distance (finding), 
953 
EUID variable (bash), 15 
eval (shell command), 37 
event timers, managing, 1424 
ex, see elvis 
exclamation points (!) 
bash special parameters, 15 
ftp command, 148 
exec (shell command), 37 
execl function, 914-916 
execle function, 914-916 
execlp function, 914-916 
exect function, 914-916 
executable files, compressing/ 
expanding, 252-253 
executables, duplicate 
(finding), 61 
executing programs, 754-755 
pausing, 813-814 
suspending, 1061 
execv function, 914-916 
execve, 754-755 
execvp function, 914-916 
exit, 739-740, 917 
shell command, 37 
xauth, 591 
exit status (commands), 26 
exp( ) function, 918 


expand, 137 
expand-tilde variable 
(readline), 28 
expanding files, see compress- 
ing/expanding files 
expansion, 18-21 
arithmetic, 20 
brace, 19 
command substitution, 20 
history, 33-34 
event designators, 33 
modifiers 34 
word designators 33 
parameter, 19-20 
pathname, 21 
process substitution, 20 
quote removal, 21 
tilde, 19 
word splitting, 21 
expire, 1292-1293 
expire.ctl, 1121-1123 
expireover, 1293-1294 
expm1( ) function, 918 
exponents, 918 
export 
cvs command, 98 
shell command, 37 
exported kernel symbols, 
displaying, 284-285 
exports, 1123-1125 
files, 1124 
options, 1123 
user 1D mapping, 
1123-1124 
expressions 
conditional, evaluating, 43 
find, 138 
gawk, 166 
gpic, 213-214 
grep, 225-226 
label, grefer, 223-224 
numeric, gtroff, 239 
regular, sed, 476-477 
ext filesystem, 1125 
ext2 filesystem, 1125 
extracting from archives, 5-7 
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fabs{ ) function, 919 
face files, converting to 
portable bitmaps, 726 
fastrm, 1294-1295 
fc (shell command), 37-38 
FCEDIT variable (bash), 17 
fchdir, 747-748 
fchmod, 748-749 
fchown, 749-750 
fclose function, 919 
fentl, 755-756 
fevt( ) function, 913-914 
fd, 1080-1083 
configuration, 1080-1082 
ioctl( ) calls supported, 1082 
FD_CLR macro, 836 
FD_ISSET macro, 836 
FD_SET macro, 836 
FD_ZERO macro, 836 
fdatasync, 756-757 
fdformat, 1295-1296 
fdisk, 1296-1297 
fdopen function, 924-925 
feof function, 919-920 
ferror function, 919-920 
fflush function, 920-921 
ffs( ) function, 921 
fg (shell command), 38 
fgetc( ) function, 945 
fgetgrent( ) function, 921-922 
fgetpos function, 927-928 
fgetpwent( ) function, 
922-923 
fgets( ) function, 945 
fgrep, 224-226 
bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 
fidds, awk, 163 
FIFOs (named pipes), 1403 
creating, 323-325, 982-983 
system logging, 1403 
FIGNORE variable (bash), 17 


files 


file descriptors 
duplicating, 23 
manipulating sets, 836 
opening, 23 
reading from, 822 
writing to, 889-890 
File menu commands, bitmap 
application, 53 
file table 
adding entries, 1428-1429 
description, 1425-1426 
initializing, 1427 
moving files to end, 1431 
removing files, 1431-1432 
structure, 1426 
table entries, 1426 
unreferenced entries, 
fetching, 1428 
file-creation mask, setting, 45 
file_table, 1425-1426 
table entries, 1426 
table structure, 1426 
file_table_init, 1427 
filechan, 1297-1298 
filename databases, updating, 
561-562 
filenames 
matching, 924 
temporary, creating, 
983-984 
fileno function, 919-920 
files 
aborting transfer, 152 
access permissions, 
changing, 61-62 
agetty, 1261 
Atari 
compressed Spectrum, 
converting to portable 
pixmaps, 494 
D egasP!1, converting to 
portable pixmaps, 378 
D egasP13, converting to 
portable bitmaps, 379 
uncompressed Spectrum, 
converting to portable 
pixmaps, 495-496 
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attributes, 59 
changing (second extended 
file sytem), 59-60 
authority (X), xauth file 
utility, 587-592 
AutoCAD slide, converting 
to portable pixmaps, 
490-491 
bash, 46 
binary 
encoding/decoding, 
565-566 
locating for commands 
575-576 
Biorad confocal, converting 
to portable graymaps, 
48-49 
bitmap, converting, 49 
to portable pixmaps, 57 
block special, creating, 325 
character special, creating, 
325 
comparing, 78-79 
compressed 
comparing, 731-732 
searching for regular 
expressions, 733 
viewing text, 733-734 
compressing/ expanding, 
248-252 
concatenation, 251 
executable files 252-253 
computing checksums, 501 
concatenating, 58-59 
configuration values, getting, 
925-926 
copying, 80-81 
beween machine, 
440-441 
converting while 108-109 
install, 272-273 
counting bytes/words/lines, 
70,574 
creating, 815-816 
mas, 880 
cuserid( ) function, 935 
cutting sections from, 90-91 


cvs, 104-105, 1117-1119 
gartup, 93 
cvsbug, 1281 
database, searching for 
patterns, 295 
date, 108 
descriptors 
dosing, 752 
duplicating, 753-754 
manipulating, 755-756 
domainname, 119 
doodle brush, converting to 
portable bitmaps, 57 
dumping, 345-346 
/etc/modules, 1152 
executing, 914-916 
exports, 1124 
face, converting to portable 
bitmaps, 726 
filesystem description, 
accessing, 935-936 
filters, hexdump, 254-256 
FITS, converting to portable 
anymaps, 142-143 
font, 1128 
adding font-metric 
information, 2 
creating, 3 
groff (creating for), 513 
formats, converting X config 
to XF86C onfig, 454 
free, 144 
gcc/g-+, 159-160, 200 
GEM IMG, converting to 
portable bitmaps, 201 
GIF, converting to portable 
anymaps, 208-209 
Gould scanner, converting 
to portable pixmaps, 211 
group, getting entries, 
921-922, 932-934 
group ownership, changing, 
61 
gtroff, 248 
gzip, forcing .gz extension, 
732-733 


HIPS, converting to 
portable graymaps, 256 
HP Paint} et, converting to 

portable pixmaps, 381 
httpd, 261 
identifying processes, 154- 
155 
identifying RCS keyword 
strings in, 262-263 
ifconfig, 1305 
ILBM, converting to 
portable pixmaps, 263-264 
image, converting to 
portable anymap, 4 
imake, 266 
Img-whatnot, converting to 
portable pixmaps, 267 
joining fields, 282-283 
linking, 293-294, 791-792 
Lisp machine bitmap, 
converting to portable 
graymaps, 292 
listing attributes, 304-305 
location, changing, 828-829 
lock, creating for shell 
scripts, 487 
login, 297 
login record, 1198-1200 
Macintosh PICT, convert- 
ing to portable pixmaps, 
379-380 
M acPaint, converting to 
portable bitmaps, 309-310 
MAKEDEV, 1321 
makefiles, creating 
dependencies in, 312-314 
man, 1248 
manual page, locating for 
commands, 575-576 
mapping/unmapping, 
799-800 
merging 
lines 347 
three way, 320 
mesg, 321 
modprobe, 111 
mount, 1332 


MS-DOS 
changing attribute flags 
315-316 
copying to/from UNIX, 
317-318, 329 
ddding, 318-319 
displaying contents, 
333-334 
manipulating (mtoolg), 
330-333 
moving, 327 
rmaming, 329-330 
mtools, testing, 330 
named, 1337 
names 
changing, 828-829 
displaying from U ene 
history file 226-227 
naming conventions 153 
netrc, 153-154 
NLM outfiles, converting 
object code into, 338-339 
nontext, printing strings 
from, 498 
numbering lines, 337-338 
object 
copying/trangating, 
341-342 
discarding symbolsfrom, 
499 
displaying information 
from, 342-343 
listing section and total 
gze5 489-490 
listing symbolsfrom, 
339-340 
offsets, repositioning, 
793-794 
opening, 815-816 
advisory locks (appl ying/ 
removing), 757 
outputting 
ends of, 504 
headers 253-254 
ownership, changing, 62-63, 
749-750 


password, editing, 
1418-1419 
PCX, converting to portable 
pixmaps, 368-369 
permissions 
changing, 748-749 
checking, 741-742 
gating modes 272-273 
Photo-CD, converting to 
portable pixmaps, 260-261 
portable anymap 
format, 1173 
reading, 971 
writing, 971-972 
portable bitmap 
format, 1170-1171 
reading, 968 
writing, 968-969 
portable graymap 
format, 1171-1172 
reading, 970 
writing, 970 
portable pixmap 
format, 1173-1174 
reading, 974 
writing, 974 
PostScript, converting to 
portable anymaps, 434- 
435 
preserving after crashes, 
128-129 
printer/plotter accounting, 
reading, 1354-1355 
printing, in reverse, 503-504 
protocol definition, 1180- 
1181 
RCS 
changing attributes, 
441-443 
cleaning, 443-445 
comparing revigons, 
445-446 
controlling access, 67 
format, 1181-1183 
freezing configuration, 
446-447 
modes 67 
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organization (diagram), 
1182 
printing log messages, 
458-460 
retrieving revisions 71-75 
specifying, 66-67 
goring revigons 64-69 
temporary files, 67 
recovering after crashes, 
129-130 
refs, generating, 87-88 
remote distribution, 
451-454 
removing, 461-462 
columns 77-78 
sts of, 1294-1295 
renaming, 334-335 
resolver configuration, 
1183-1184 
reversing lines, 457 
searching for (in directories), 
137-142 
SF86C onfig, generating, 
633 
SGI image, converting to 
portable anymaps, 
483-484 
shar, unpacking, 560-561 
shrinking, 488 
Solitaire, converting to 
portable anymaps, 
488-489 
sorted, removing duplicate 
lines, 560 
source, locating for 
commands, 575-576 
spell-checking utilities, 281 
splitting, 85-86, 119-120, 
494-495 
status, getting, 863-864 
string table C source files/ 
headers, 314-315 
substituting definitions into, 
500-501 
suffixes, list of, 1249-1252 
Sun raster, converting to 
portable anymaps, 438 
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swapping 
enabling/disabling, 1401 
garting/topping, 866-867 
symbolic links, 867-869 
synchronizing 
in-core data, 756-757 
in-core tate, 758-759 
with memory maps 811 
tag 
emacs, 135-137 
vi, 135-137 
tags, generating, 87-88 
temporary 
creating, 983, 1053-1054 
naming, 1049, 1054 
text 
converting for printing, 
429-430 
creating gcal resource files 
from, 558 
sorting, 492-493 
TIFF, converting to portable 
anymaps, 515-516 
time zone information, 
1197-1198 
timestamps (changing), 536 
transfer parameters, 153 
TrueVision T arga, convert- 
ing to portable pixmaps, 
515 
truncating, 879-880 
UNIX 
copying betwen sytens, 
563-565 
copying to MS-DOS, 335 
retoring filaames 324- 
325 
U senix FaceSaver, convert- 
ing to portable graymaps, 
147 
user group, 1131 
UUCP transfer requests, 
processing, 1415-1417 
uuencode, format, 1200 
XFree86, 638-639, 
1201-1208 
D evice tions 
1204-1206 


Files section, 1201 
Keyboard section, 1202 
M onitor sections, 
1203-1204 
Pointer section, 
1202-1203 
Screen sections, 
1206-1208 
Saver lags section, 1201 
XIM_, converting to portable 
pixmaps, 654 
YUV, converting to portable 
pixmaps, 730-731 
Z, recompressing to GZ, 
734-735 
Zass confocal, converting to 
portable anymaps, 732 


filesystem checks 


group identity (setting), 
843-844 
user identity (setting), 844 


filesystem description file, 
accessing, 935-936 
filesystems, 1125-1126 


buffers, flushing, 1401-1402 
building, 1325-1326 
checking, 1298-1300 
debugger, 1284-1285 
commands, 1284-1285 
options, 1284 
ddeting names from, 1008 
device entries, maintaining, 
1320-1321 
dumping information, 1289 
ext, 1125 
ext2, 1125 
hierarchy, description of, 
1236-1238 
H igh Sierra, 1125 
hpfs, 1125 
iso9660, 1125 
MINIX, 1125 
cons gency checker, 
1300-1301 
creating, 1326-1327 
mounting/dismounting, 
802-804, 1328-1332 


msdos, 1125 
names, deleting, 882 
nepfs, 1126 
nfs, 1125 
export list, 1123-1125 
proc, 1125 
quotas 
summarizing, 1376 
turning on/off, 
1372-1373 
repairing, 1298-1299 
Rock Ridge, 1125 
root, mounting, 849 
scanning, 1371-1372 
second extended 
checking, 1289-1291 
creating, 1324-1325 
lot+found directory, 1327 
tunable parameters 
(adjusing), 1412-1413 
setup, 849 
smb, 1126 
static information, 
1126-1127 
statistics, getting, 883-884, 
865-866 
sysv, 1125 
table of, 1427-1428 
type information, getting, 
871 
umsdos, 1125 
vfat, 1125 
xiafs, 1125 


filesystems command, 
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Laplacian relief, running on 
portable pixmaps, 413 
more, 327-328 
commands 328 
qvironment, 328 
options, 327-328 
nonlinear (pnmnifilt), 
390-391 
nroff output, 77 
reverse line feeds, 76 


find, 137-142 
actions, 140-142 
expressions, 138 
numeric arguments, 
138-140 
operators, 142 
options, 138 
findaffix, 274, 280 
bugs, 282 
files, 281 
se als ispal 
finger daemons, configurable, 
1106-1109 
configuration file, 
1109-1115 
error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 
finger information, changing, 
60 
finite ) function, 959 
first in - first out scheduling, 
833-834 
FITS files, converting to 
portable anymaps, 142-143 
fitstopnm, 142-143 
floating-point numbers 
absolute value, 919 
converting 
to fractional/integral 
components 927 
to strings 913-914, 
930-931 
extracting integral and 
fractional values, 984 
multiplying, by integral 
powers of 2, 961 
flock, 757 
floor( ) function, 923 
floppy disks 
devices, 1080-1083 
configuration, 1080-1082 
drivers, boot-time 
parameters, 1223-1224 
formatting, 1295-1296 
marking bad blocks, 316 
parameters, setting, 1391 
fmod( ) function, 923 


fmt, 143 
fnmatch() function, 924 
fold, 143-144 
font files 
adding font-metric 
information, 2 
creating, 3 
font formats 
converting 
Bitmap Distribution to 
Portable Compiled, 47 
packed format to portable 
bitmaps 381 
PostScript PFB format to 
ASCII, 369 
groff_font, 1127-1129 
DESC file 1127-1128 
font servers (X) 
displaying information 
about, 145 
generating BDF fonts, 
146-147 
listing fonts, 145-146 
fonts 
files, 1128 
creating for groff, 513 
grops styles, 231-232 
man pages, 1247 
X 
displaying all characters 
in, 633-636 
listing, 670-671 
X font server, 641-643, 689 
configuration, 642 
naming, 643 
fopen function, 924-925 
errors, 925 
mode argument sequences, 
924-925 
return values, 925 
fork, 758 
form (ftp command), 149 
formatting 
dates, strftime( ) function, 
1032-1034 
documents, gtroff, 237-248 
equations, 202-206 
floppy disks, 1295-1296 
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input, 1013-1015 
conversions, 1014-1015 
flags 1014 
line lengths, 143 
man pages, 1246-1248 
fonts 1247 
macros 1248 
preamble, 1246-1247 
gctions, 1247-1248 
output, 992-996, 
1022-1023 
conversion specifiers 994 
examples, 995 
flags 993-994 
technical papers 
groff_me macros, 
1225-1227 
groff_mm macros 
1227-1234 
groff_ms macros, 
1234-1236 
times, strftime( ) function, 
1032-1034 
troff tables, 236-237 
fpathconf( ) function, 
925-926 
fprintf function, 992-996 
fpurge function, 920-921 
fputc( ) function, 997-999 
fputs( ) function, 997-999 
fractal forgeries, 404-407 
fread function, 926-927 
free, 144 
free( ) function, 976 
freopen function, 924-925 
frexp( ) function, 927 
fscanf function, 1013-1015 
fsck, 1298-1300 
fsck.minix, 1300-1301 
fseek function, 927-928 
fsetpos function, 927-928 
fsinfo, 145 
fslsfonts, 145-146 
fstab, 1126-1127 
file format/options, 
1165-1167 
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fstat, 863-864 
fstatfs, 865-866 
fstobdf, 146-147 
fstopgm, 147 
fsync, 758-759 
ftell function, 927-928 
ftime function, 928-929 
ftok function, 929-930 
FT P (File T ransfer 
Protocol), DARPA server, 
1301-1304 
ftp, 147-154 
aborting transfer, 152 
bugs, 154 
commands, 148-152 
1 148 
$, 148 
?,152 
account, 148 
append, 148 
axii, 148 
bdl, 148 
binary, 148 
bye, 148 
case, 148 
cd, 148 
cdup, 148 
chmod, 148 
clos 148 
cr, 148 
debug, 149 
ddde 148 
dir, 149 
disconnect, 149 
form, 149 
gd, 149 
glob, 149 
hash, 149 
hdp, 149 
idle 149 
Icd, 149 
Is, 149 
macdé, 149 
mddete 149 
mdir, 150 
mgeé, 150 
mkdir, 150 


mls, 150 
mode, 150 
modtime, 150 
mput, 150 
newer, 150 
nlis, 150 
nmap, 150 
ntrans 150-151 
open, 151 
prompt, 151 
proxy ftp, 151 
put, 151 
pwd, 151 
quit, 151 
quote, 151 
rev, 151 
reget, 151 
remotehdp, 151 
remotedatus, 151 
rename, 151 
reset, 151 
retart, 151 
rmdir, 152 
runique 152 
gad, 152 
gndport, 152 
gte, 152 
gze, 152 
gatus, 152 
gruct, 152 
gsten, 152 
trace 152 
type 152 
uma, 152 
usy, 152 
verboss, 152 
environment variables, 154 
file naming conventions, 
153 
file transfer parameters, 153 
netrc file, 153-154 
options, 147-148 
tenex, sendport, 152 
ftpd, 1301-1304 
bugs, 1303 
FT P requests supported, 
1302-1303 
options, 1302 


ftruncate, 879-880 
ftw( ) function, 930 
full-duplex connections, 
shutting down, 855 
function bindings, displaying, 
35 
functions 
calling at termination, 
897-898, 988 
headers, displaying, 455-456 
library, undocumented, 
1060 
portable pixmap programs, 
973-974 
color names 974 
memory management, 973 
reading files 974 
writing files 974 
fuser, 154-155 
fwrite function, 926-927 
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g++, 155-160, 174-201 
bugs, 160 
copying, 160, 201 
filename suffixes, 174-175 
files, 159-160, 200 
options, 155-159, 175-178 
assemble, 181 
code gneration, 198-199 
debugging, 186-187 
directory, 182-183 
language, 178-180 
linker, 181-182 
machine dependent, 
191-198 
optimization, 188-190 
preprocesor, 180-181 
target, 190-191 
warning, 183-186 
pragmas, 159, 200 
g3topbm, 160-161 
games, 1210 
gawk, 161-173 
actions, 165-166 
arithmetic functions, 
168-169 


bugs, 172 
reporting, 172-173 
control statements, 167 
environment variables, 172 
fidds, 163 
functions, 170 
GNU ettensions, 171 
historical awk features 
supported, 172 
1/0 statements, 167 
operators, 166-167 
options, 161-162 
patterns, 165-166 
POSIX compatibility, 171 
printf statenent, 167-168 
program execution, 162-163 
regular expressions, 166 
special filenames, 168 
sprintf( ) function, 167-168 
string constants, 169-170 
string functions, 169 
time functions, 169 
variables, 163-165 
arrays, 164 
built-in, 163-164 
typing and converson, 
164-165 
version information, 172 
gcal, 173-174 
running one day ahead, 506 
resource files, creating from 
text files, 558 
gcc, 174-201 
assembling output, 8-9 
bugs, 201 
copying, 201 
filename suffixes, 174-175 
files, 200 
options, 175-178 
asemble, 181 
code gneration, 198-199 
debugging, 186-187 
directory, 182-183 
language, 178-180 
linker, 181-182 
machine-dependent, 
191-198 


optimization, 188-190 
preprocessor, 180-181 
target, 190-191 
warning, 183-186 
pragmas, 200 
gcvt( ) function, 930-931 
GEM IMG files, converting to 
portable bitmaps, 201 
gemtopbm, 201 
GenerateM essagelD routine, 
964 
geqn, 202-206 
automatic spacing, 203 
bugs, 206 
customization, 204-205 
equation components, 
202-203 
files, 206 
fonts, 206 
macros, 206 
new primitives, 203-204 
options, 202 
get (ftp command), 149 
get_current_dir_name{ ) 
function, 931 
get_empty_filp, 1428 
get_kernel_syms, 800-802 
getc( ) function, 945 
getchar( ) function, 945 
GetC onfigValue routine, 965 
getcwd( ) function, 931 
getdents, 759 
getdirentries function, 
931-932 
getdomainname, 760 
getdtablesize, 760-761 
getegid, 761 
getenv( ) function, 932 
geteuid, 773 
GetFileC onfigValue routine, 
965 
GetFQDN routine, 965 
getgid, 761 
getgrent( ) function, 932-933 
getgrgid( ) function, 933-934 
getgrnam( ) function, 933-934 
getgroups, 761-762 


getr usage 


gethostid, 762-763 
gethostname, 763 
getitimer, 763-764 
getlist, 206-207 
getlogin( ) function, 934-935 
getmntent( ) function, 
935-936 
GetM oderatorAddress 
routine, 965 
getnetbyaddr subroutine, 
936-937 
getnetbyname subroutine, 
936-937 
getnetent subroutine, 936-937 
getopt, 207-208 
getopt( ) function, 937-940 
environment variables, 939 
getopt_long( ) example, 
939-940 
return value, 939 
getopt_long( ) function, 
938-940 
getopt_long_only( ) function, 
938 


getopts (shell command), 38 

getpagesize, 765 

getpass function, 940-941 

getpeername, 765 

getpgid, 845-846 

getpgrp, 845-846 

getpid, 766 

getppid, 766 

getpriority, 766-767 

getprotobyname{ ) function, 
941-942 

getprotobynumber( ) 
function, 941-942 

getprotoent( ) function, 
941-942 

getpw( ) function, 942-943 

getpwent( ) function, 943 

getpwnam( ) function, 944 

getpwuid( ) function, 944 

GetResourceU sage routine, 
965 

getrlimit, 767-768 

getrusage, 767-768 
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ga@x ) function 


gets( ) function, 945 
getservbyname{ ) function, 
946 
getservbyport( ) function, 946 
getservent( ) function, 946 
getsid, 768 
getsockname, 769 
getsockopt, 769-772 
bugs, 772 
errors, 771 
options recognized, 770-771 
SO_BROADCAST, 771 
SO_DEBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO_KEEPALIVE, 770 
SO_LINGER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIMEO, 771 
SO_REUSEADDR, 770 
SO_SNDBUF, 771 
SO_SNDLOWAT, 771 
SO_SNDTIMEO, 771 
SO_TYPE, 771 
return value, 771 
GetTimd nfo routine, 965 
gettimeofday, 772-773 
getuid, 773 
getusershell( ) function, 
946-947 
getutent( ) function, 947 
getutid( ) function, 947 
getutline{ ) function, 948 
getw function, 948 
getwd( ) function, 931 
GIF files, converting to 
portable anymaps, 208-209 
giftopnm, 208-209 
giles, gpic, 215 
gindxbib, 209-210 
glob (ftp command), 149 
glob( ) function, 949-950 
glob_dot_filenames variable 
(bash), 17 
globfree( ) function, 949-950 


glookbib, 210 
gmtime, 984-986 
gmtime{ ) function, 909-910 
gnroff, 210-211 
GNU linker, 287-291 
copying, 291 
environment, 291 
options, 288-291 
GNU ar, see ar 
GNU as, seeas 
GNU Bourneagain shell, see 
bash 
Gould scanner files, convert- 
ing to portable pixmaps, 211 
gouldtoppm, 211 
gpic, 211-215 
bugs, 215 
commands, 212-213 
expressions, 213-214 
file, 215 
mode, 212 
options, 211-212 
versus pic, 212-215 
gprof, 216-217 
graph profile data, displaying, 
216-217 
graphics (ASCII), converting 
to portable graymap, 10 
graphs 
system load average, 533 
topological sorts, 542 
grayscale ramps, generating, 
374-375 
greater than signs (>), 
redirection operator, 21 
grefer, 217-224 
bibliographic databases, 219 
bugs, 224 
citations, 219-220 
commands, 220-222 
files, 224 
label expressions, 223-224 
macro interface, 224 
options, 218-219 


grep, 224-226 
bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 
grodvi, 227-228 
groff, 228-230 
availability, 230 
bugs, 230 
creating font files for, 513 
environment, 229 
files, 229 
guessing options, 230 
interpreting .so requests, 
236 
options, 229 
output, converting to T eX 
dvi format, 227-228 
PostScript driver, 230-235 
preprocessing references, 
217-224 
typewriter device driver, 235 
groff_font format, 1127-1129 
DESC file, 1127-1128 
groff_me, 1225-1227 
groff_mm, 1227-1234 
extensions, 1227-1229 
number variables, 
1233-1234 
strings, 1233 
variables, 1229-1230 
groff_ms, 1234-1236 
groff_out, 1129-1131 
grog, 230 
grops, 230-235 
files, 234 
font styles, 231-232 
options, 231 
X commands, 232-233 
grotty, 235-236 
group, 1131 
Group 3 fax files, converting 
to portable bitmaps, 
160-161 
group access lists 
getting/setting, 761-762 
initializing, 955 


group file entries, getting, 
921-922, 932-934 
group identity, setting, 845 
group IDs 
getting/setting, 761, 
845-846 
real and effective, setting, 
846-847 
group ownership (files), 
changing, 61 
groups 
adding to system, 
1258-1259 
logging into, 336-337 
process, sending signals to, 
960 
grow_files, 1428-1429 
grttoppm, 436-437 
gsoelim, 236 
gtbl, 236-237 
gtroff, 237-248 
environment, 248 
escape sequences, 239-240 
files, 248 
fractional point sizes, 238- 
239 
incompatibilities, 247-248 
long names, 238 
numeric expressions, 239 
options, 238 
requests, 241-244 
extended, 244 
number registers 245-246 
warnings, 246-247 
gunzip, 248-249 
se ald gzip 
gzexe, 252-253 
gzip, 248-252 
bugs, 252 
diagnostics, 251-252 
environment, 251 
options, 249-250 
gzip files, forcing .gz exten- 
sion, 732-733 


H 


handling signals, 857-858 
hard disks 
boot-time parameters, 
1220-1221 
devices, 1083 
partition tables, manipulat- 
ing, 1296-1297 
hard drives, partitioning, 
1265-1269 
hard-reset( ) action (xterm), 
715 
hardware, video (identifying), 
501-503 
hash 
ftp command, 149 
shell command, 38 
hash tables 
creating, 951 
freeing memory, 951 
searching, 951 
hasmntopt( ) function, 
935-936 
hcreate{ ) function, 951-952 
hd, 1083 
hdestroy( ) function, 951 
head, 253-254 
H eaderC leanFrom routine, 
964 
H eaderFind routine, 964 
headers function, displaying, 
455-456 
hdp 
ftp command, 149 
shell command, 38 
xauth command, 591 
here-documents, 22-23 
hexdump, 254-256 
hier, 1236-1238 
directories, 1236-1238 
/, 1236 
/bin, 1236 
/boot, 1236 
dev, 1236 
Idos, 1236 
/etc, 1236 


HIST SIZE variable (bash) 


lecdxkd, 1236 
/ecg/X11, 1236 
/home, 1236 
/lib, 1236 
/mnt, 1236 
/proc, 1236 
/din, 1237 
/tmp, 1237 
lux, 1237 
/usx/X11R6, 1237 
/usx/X11R6/bin, 1237 
/ux/X11R6/lib, 1237 
/us/X11R6/lib/X11, 1237 
/usX11R6/incud@X11, 
1237 
hierarchies 
directory (creating), 323 
filesystem, description of, 
1236-1238 
High Sierra filesystem, 1125 
HIPS files, converting to 
portable graymaps, 256 
hipstopgm, 256 
histchars variable (bash), 
17-18 
HISTCMD variable (bash), 
16 
HISTFILE variable (bash), 17 
HISTFILESIZE variable 
(bash), 17 
histograms 
drawing for PGM or PPM 
files, 388 
portable pixmaps, printing, 
408 


history, 1131-1132 
control variable (bash), 17 
cvs command, 99 
shell command, 39 
history expansion (bash), 
33-34 
event designators, 33 
modifiers, 34 
word designators, 33 
history lists (bash), 32-33 
displaying, 39 
HISTSIZE variable (bash), 17 
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HOME variable (bash) 


HOME variable (bash), 16 
/home directory, 1236 
horizontal-scroll-mode 
variable (readline), 28 
host, 257-258 
bugs, 258 
customizing, 258 
options, 257-258 
host byte order, converting 
between network byte order, 
901-902 
host IDs, printing, 258-259 
hostid, 258-259 
hostname, 259-260, 
1238-1239 
hostname_completion_file 
variable (bash), 18 
hostnames 
displaying, 259-260 
looking up, 257-258 
resolving, 1238-1239 
hosts 
identifiers, getting/setting, 
762-763 
names, getting/setting, 763 
sending messages to users 
on, 473 
hosts.nntp, 1132-1133 
hosts.nntp.nolimit, 
1132-1133 
hosts access, 1133-1136 
access control files, 1133 
access control rules, 1133 
bugs, 1136 
diagnostics, 1136 
files, 1136 
operators, 1134 
patterns, 1133-1134 
remote username lookup, 
1134-1135 
shell commands, 1134 
wildcards, 1134 
hosts _access( ) function, 
950-951 
hosts _ctl( ) function, 950-951 
hosts_ options, 1137-1139 
diagnostics, 1139 
options, 1137 


HOSTTYPE variable (bash), 
16 

HP Paintjet files, converting 
to portable pixmaps, 381 

hpcdtoppm, 260-261 

hpfs filesystem, 1125 

hsearch( ) function, 951-952 

htonl( ) function, 901-902 

htons{ ) function, 901-902 

httpd, 261 

hyperbolic cosines, 908 

hyphens (-), bash special 
parameters, 15 

hypot( ) function, 953 


1/0 
awk statement, 167 
port permissions, setting, 
788 
ports, functions, 816 
privilege leva, changing, 
788-789 
standard |/O library, 
1025-1027 
IC Ccancel routine, 956 
IC Cclose routine, 956 
IC Ccommand routine, 956 
IC Copen routine, 956 
IC C pause routine, 956 
IC Creserve routine, 956 
IC Csettimeout routine, 956 
icombine, 274, 281 
files, 281 
se als ispal 
icontopbm, 262 
ident, 262-263 
idle, 774 
errors, 774 
ftp command, 149 
return value, 774 
ID s (group), searching for 
matches, 1429 
$if parser directive (readline), 
28-29 
ifconfig, 1304-1305 


IFS variable (bash), 16 
ignore{ ) action (xterm), 713 
IGNOREEOF variable (bash), 
17 
ijoin, 274, 281 
files, 281 
ge ald ispal 
ILBM files, converting to 
portable pixmaps, 263-264 
ilbmtoppm, 263-264 
image files, converting to 
portable anymap, 4 
image parameter, values, 1374 
imake, 264-267 
environment variables, 267 
files, 266 
input, 266 
options, 265 
X Window Systen, 266 
Imakefiles, creating M akefiles 
from, 672 
Img-whatnot file, converting 
to portable pixmaps, 267 
imgtoppm, 267 
import (cvs command), 100 
in_group_p, 1429 
inb, 816 
inb_p, 816 
inbound zone transfers, 
1333-1334 
index( ) function, 953 
indexes, archives (generating 
for), 437-438 
inet_addr( ) function, 954 
inet_aton( ) function, 954 
inet_Inaof( ) function, 954 
inet_makeadadr( ) function, 
954 
inet_netof( ) function, 954 
inet_network( ) function, 954 
inet_ntoa( ) function, 954 
inetd, 1305-1307 
inews, 267-269 
infinite results 
returning value for, 954-955 
testing for, 959 
infnan( ) function, 954-955 


info, 269-270 
commands, 269-270 
environment, 270 
options, 269 
info command (xauth), 591 
init, 1307-1309 
diagnostics, 1309 
files, 1308 
run levels, 1308 
init_module, 800-802 
init_timer, 1424 
initgroups( ) function, 955 
initializing 
terminals, 539-542 
X sessions, 496-497 
initstate( ) function, 
1001-1002 
inittab, 1139-1141 
inittab file, 1398 
inl, 816 
inl_p, 816 
inn.conf, 1141-1142 
innconfval, 270-271 
innd, 1309-1312 
control messages, 1310 
header modifications, 1311 
logging, 1311-1312 
protocol differences, 
1310-1311 
inndcomm routines, 956 
inndstart, 1309-1312 
INNVersion routine, 966 
innwatch.ctl, 1142-1144 
innxmit, 1312-1313 
input 
formatting, 1013-1015 
conversons 1014-1015 
flags 1014 
reading, 27-32 
controlling key bindings 
27 
denoting keystrokes, 27 
macro definitions, 28 
readline commands, 
29-32 
redirecting, 22 


input lines, wrapping, 143- 
144 


input, see elvis 
INPUTRC variable (bash), 17 
insb, 816 
insert( ) action (xterm), 713 
insert-eight-bit( ) action 
(xterm), 713 
insert-selection( ) action 
(xterm), 713 
insert-seven-bit( ) action 
(xterm), 713 
insert_file_free, 1429 
insl, 816 
insmod, 271-272 
insque( ) function, 957 
install, 272-273 
installing 
loadable modules, 271-272 
rstartd, 469 
spottopgm, 495 
sysklogd, 1403 
installit, 273-274 
insw, 816 
integers 
absolute values, 892-893 
converting, between host 
and network byte order, 
901-902 
dividing, 911 
floating-point remainders, 
913, 923 
returning quotient and 
remainder, 961 
long, labs, 960-961 
rounding, 904 
downward, 923 
to, 1011-1012 
interactive shells, 45 
interfaces 
name daemon control, 
1338-1339 
network 
attaching to srial line 
1399 
configuring, 1304-1305 
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serial mouse, 1092-1094 
Microsoft protocol, 1093 
MM protocol, 1094 
M ouseSystems protocol, 
1093 
Sun protocol, 1093 
interned atoms, listing, 
668-669 
Internet 
addresses, manipulating, 
953-954 
extended | nternet services 
daemon, 655-664 
inetd superserver, 
1305-1307 
services, listing, 1184-1186 
InterN etN ews 
buffered file writing, 1264- 
1265 
configuration data, 
1141-1142 
daemon, 1309-1312 
control messages 1310 
controlling, 1276-1279 
filewriting, 1297-1298 
InterN etN ews library 
clientlib, 904-905 
INND communication 
routines, 956 
libinn routines, 962-966 
CAdose, 964 
CAlistopen, 964 
CAopa, 964 
CloseO nE xec, 965 
DD check, 965 
DD end, 965 
DD gart, 965 
GaConfigValue 965 
GeFileConfigValue, 965 
GaFQDN, 965 
GeM oderatorA ddres, 
965 
GedResourceu sage 965 
GaTimanfo, 965 
H eaderFind, 964 
INN Version, 966 
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LockFile 965 
NNT Pcheckartide 965 
NNT Pconnect, 965 
NNT Plocalopen, 965 
NNT Prenoteopen, 965 
NNT Psendarticle, 966 
NNT Psendpassword, 966 
Radix32, 966 
ReadinD exriptor, 966 
ReadinFile 966 
SAN onBlocking, 965 
Quick 1/0, 998 
interrupt key sequence, 
routing, 1425 
interval timers 
getting/setting value, 
763-764 
ITIMER_PROF, 764 
ITIMER_REAL, 764 
ITIMER_VIRTUAL, 764 
value definitions, 764 
inverse hyperbolic cosines, 
893-894 
inverse hyperbolic sines, 895 
inverse hyperbolic tangents, 
897 
inverted indexes, biblio- 
graphic databases, 209-210 
invocation, bash, 45-46 
inw, 816 
inw_p, 816 
ioctl, 774-788 
arguments, 787-788 
calls 
consoles 1074-1080 
fd device support, 1082 
list of, 775-786 
Ip, 1090-1091 
sd, 1095-1096 
g, 1097-1100 
duplicates, 788 
errors, 774 
return value, 774 
ioperm, 788 
iopl, 788-789 
errors, 789 
return value, 789 


IP 
dialup connections, handler, 
1285-1288 
routing table (manipulat- 
ing), 1379-1380 
ipc, 789, 1144-1146 
message queues, 1145 
resource access permissions, 
1144-1145 
semaphore sets, 1145-1146 
shared memory segments, 
1146 
ipc facilities 
getting information on, 
1314 
removing, 1313-1314 
IPC system calls, 789 
ipcrm, 1313-1314 
ipcrs, 1314 
isalnum( ) function, 958 
isalpha( ) function, 958 
isascii( ) function, 958 
isatty function, 958-959 
isblank( ) function, 958 
iscntrl( ) function, 958 
isdigit( ) function, 958 
isgraph( ) function, 958 
isinf( ) function, 959 
islower( ) function, 958 
isnan( ) function, 959 
ISO character sets 
2022, 1066 
4873, 1066 
8859, 1064-1065 
8859-1, 1239-1242 
alphabets 1240 
characters, 1240-1242 
iso9660 filesystem, 1125 
ispell, 274-279, 1084-1090 
affix file, 1084-1085 
alternate string characters, 
1087 
bugs, 282 
capitalization rules, 279 
character-set section, 1086 
commands, 274-275 
flags, 1088 


headers, 1085 
options, 275-279 
options statements, 
1085-1086 
prefix/suffix tables, 1088 
root words 
case, 1084 
extending, 1085 
modifying, 1088-1089 
isprint( ) function, 958 
ispunct( ) function, 958 
isspace( ) function, 958 
issue, 1146-1147 
isupper( ) function, 958 
isxdigit( ) function, 958 
ITIMER_PROF interval 
timer, 764 
ITIMER_REAL interval 
timer, 764 
ITIMER_VIRTUAL interval 
timer, 764 


jO( ) function, 959 

j1( ) function, 959 

jn( ) function, 959 

job control, 24-25 

jobs, displaying, 39 

jobs (shell command), 39 
join, 282-283 

jrand48( ) functions, 912 
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kbdrate, 1314-1315 
Kerberos authentication, 461 
kernd 
boot-time parameters, 
1216-1224 
Adaptec configurations, 
1219-1220 
argument list, 1216-1217 
BusLogic configuration, 
1220 
busnous drivers 1224 
cards not accepting, 1220 


CD-ROMs 1222-1223 
debug argument, 1217 
Ethene devices, 1223 
floppy dix drivers, 
1223-1224 
future domain configura- 
tion, 1220 
hard dixs, 1220-1221 
mem= argument, 1218 
no-hit argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 
ramdisk= argument, 1218 
reboot=warm argument, 
1218 
reerve= argument, 
1217-1218 
ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI device arguments, 
1218-1219 
SCSI tape configuration, 
1219 
Seagate ST -0x 
configuration, 1220 
sound drivers 1224 
Trantor T 128 
configuration, 1220 
exported symbols, display- 
ing, 284-285 
log buffer, 873 
message ring buffer, reading/ 
clearing, 872-874 
modules, loading at boot 
time, 1152 
name, getting, 880-881 
ring buffer, controlling, 
1288-1289 
kerndl clock, adjusting, 
742-743 
kerndl log daemon, 
1315-1317 
kernd logging, 1402 
kernel_mktime, 1430 
key bindings, displaying, 35 


key combinations, 
Ctrl+Alt+D el (setting 
function), 1279 
key sequences (interrupt), 
routing, 1425 
keyboard repeat rate, 
resetting, 1314-1315 
keymap variable (readline), 28 
keymap( ) action (xterm), 713 
keymaps (X), modifying, 
672-676 
keywords, RCS, identifying in 
files, 262-263 
kill, 283-284, 790 
bugs, 790 
errors, 790 
options, 283 
return value, 790 
shell command, 39 
killall, 284 
killing client connections (X 
servers), 666-667 
killpg, 790-791, 960 
klogd, 1315-1317 
files, 1317 
options, 1315 
signal handling, 1316-1317 
kmem, 1091-1092 
KO18-R character set, 1065 
ksyms, 284-285 
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labs( ) function, 960-961 
Laplacian relief filters, 
running on portable 
pixmaps, 413 
last, 285-286 
Latin-1 character set, 1064 
Latin-2 character set, 1064 
Latin-3 character set, 1064 
Latin-4 character set, 1064 
Latin-5 character set, 1065 
Latin-6 character set, 1065 
Ibxproxy, 286-287 
network connections, 286 
options, 286 
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Icd (ftp command), 149 
Icong48( ) functions, 912 
Id, 287-291 
copying, 291 
environment, 291 
options, 288-291 
Idexp( ) function, 961 
Idiv( ) function, 961 
less than signs (<), redirection 
operator, 21 
let (shell command), 39 
letters, converting 
to lowercase, 1055-1056 
to uppercase, 1055-1056 
Ifind( ) function, 975-976 
Igamma( ) function, 962 
/lib directory, 1236 
libinn routines, 962-966 
CAclose, 964 
CAlistopen, 964 
CAopen, 964 
CloseO nE xec, 965 
DD check, 965 
DDend, 965 
D Dstart, 965 
GeConfigValue 965 
GeFileC onfigV alue 965 
GeaFQDN, 965 
GetM oderatorAddress, 965 
GetResourceU sage, 965 
GeT imelnfo, 965 
H eaderFind, 964 
INN Version, 966 
LockFile, 965 
NNT Pcheckarticle, 965 
NNT Pconnect, 965 
NNT Plocalopen, 965 
NNT Premoteopen, 965 
NNT Psendarticle, 966 
NNT Psendpassword, 966 
Radix32, 966 
ReadInD escriptor, 966 
ReadInFile, 966 
SetN onBlocking, 965 
libpbm routines, 966-969 
constants, 968 
endian i/o, 967 
errors, 967 
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file management, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 
reading files, 968 
types, 968 
writing files, 968-969 
libpgm routines, 969-970 
constants, 969 
initialization, 969 
memory management, 969 
reading files, 970 
types, 969 
writing files, 970 
libpnm routines, 970-972 
constants, 970 
format promotion, 972 
initialization, 971 
memory management, 971 
reading files, 971 
types, 970 
writing files, 971-972 
XEL manipulation, 972 
XEL manipulations, 971 
libppm, 973-974 
color names, 974 
memory management, 973 
reading files, 974 
writing files, 974 
libraries 
shared, selecting, 883 
standard 1/0 , 1025-1027 
library functions, undocu- 
mented, 1060 
LILO, 1216 
configuration file, 
1147-1151 
global options, 1148-1149 
kernel options 1150-1151 
per-image section, 
1149-1150 
line buffered streams, 1016 
line printer 
control program, 1317-1318 
devices, 1090-1091 
ioctl( ) calls 1090-1091 
spooler daemon, 1318-1320 


linear searches, arrays, 
975-976 
LINENO variable (bash), 15 
link, 791-792 
linkers, Id (GNU linker), 
287-291 
copying, 291 
environment, 291 
options, 288-291 
linking files, 293-294, 791- 
792 
Lisp Machine bitmap files, 
converting to portable 
graymaps, 292 
lispmtopgm, 292 
list 
bash command, 13 
xauth command, 591 
listen, 792-793 
lists 
bash, 12-13 
columnating, 78 
variable argument (declar- 
ing), 1023-1024 
Ikbib, 292-293 
Ilseek, 793 
In, 293-294 
Indir, 294 
loadable modules 
installing, 271-272 
support, 800-802 
unloading, 462-463 
viewing, 305 
loadlin program, 1216 
local (shell command), 39 
local descriptor table, reading/ 
writing, 800 
local variables, creating, 39 
locale, 1243-1244 
setting, 1018-1019 
localeconv, 974-975 
localtime, 909-910, 984-986 
locate, 295 
lock files, creating for shell 
scripts, 487 
LockFile routine, 965 


locking memory 
mlock, 796-797 
mlockall, 797-798 
locks (advisory), applying/ 
removing open files, 757 
log (cvs command), 100 
log( ) function, 918 
log10( ) function, 918 
logip( ) function, 918 
logarithms, 918 
1 plus argument, 918 
base-10, 918 
logger, 295-296 
logging 
innd, 1311-1312 
kernel, 1402 
system, 1402-1404 
configuration file 
1402-1403 
FIFOs 1403 
messages, 1404-1405 
remote 1403 
Usenet, log file 
maintenance, 1346-1347 
login, 296-297 
login shells, 45 
changing, 63 
exiting, 39 
logins 
changing groups, 336-337 
displaying last, 285-286 
login command, 296-297 
login record files, 
1198-1200 
preventing, 1168 
remote, 460-461 
Kerberos authentication, 
461 
root, tty lines (listing), 1184 
shells, pathnames, 1186 
logout (shell command), 39 
logs 
system 
making entries, 295-296 
sanding mesages to, 
1045-1046 
xinetd, 661-663 


long integers, absolute values, 
960-961 
longjmp( ) function, 975 
look, 297-298 
loops 
exiting, 35 
resuming, 36 
lowercase, converting letters 
to, 1055-1056 
Ip, 1090-1091 
Ip devices, setting parameters, 
1413-1414 
Ipc, 1317-1318 
commands, 1317-1318 
diagnostics, 1318 
Ipd, 1318-1320 
key characters, 1319 
options, 1319 
Ipq, 298-299 
bugs, 299 
diagnostics, 299 
environment, 299 
options, 298-299 
Ipr, 299-301 
bugs, 301 
diagnostics, 301 
environment, 300 
options, 299-300 
Iprm, 301-302 
bugs, 302 
diagnostics, 302 
environment, 302 
options, 301 
Iptest, 302 
lrand48( ) functions, 912 
Is, 303-304 
Is (ftp command), 149 
Isattr, 304-305 
Isearch( ) function, 975-976 
Iseek, 793-794 
Ismod, 305 
Istat, 863-864 
lynx, 306-309 
commands, 308-309 
options, 306-308 


M 


macdef (ftp command), 149 
Macintosh PICT files, 
converting to portable 
pixmaps, 379-380 
MacPaint files, converting to 
portable bitmaps, 309-310 
macptopbm, 309-310 
magic cookies, generating, 
317 
mail addressing, 1244-1246 
abbreviations, 1245 
case sensitivity, 1245 
compatibility, 1245 
postmasters, 1246 
routing, 1245 
mail, see e-mail 
MAIL variable (bash), 16 
MAIL_WARNING variable 
(bash), 16 
mailaddr, 1244-1246 
abbreviations, 1245 
bugs, 1246 
case sensitivity, 1245 
compatibility, 1245 
postmasters, 1246 
routing, 1245 
MAILCHECK variable (bash), 
16 
MAILER environment 
variable, 529 
MAILPATH variable (bash), 
16 
make, 310-312 
imake preprocessor, 264-267 
options, 311 
makeactive, 1342-1344 
makedepend, 312-314 
algorithm, 313 
bugs, 314 
options, 312-313 
MAKED EV, 1320-1324 
files, 1321 
options, 1321-1324 
MAKED EV.cfg, 1151 


memchr( ) function 


makefiles 
creating dependencies in, 
312-314 
creating from Imakefiles, 
672 
makehistory, 1342-1344 
makestrs, 314-315 
bugs, 315 
directives, 315 
options, 314 
syntax, 314-315 
malloc( ) function, 976 
man, 1246-1248 
man pages, formatting, 
1246-1248 
fonts, 1247 
macros, 1248 
preamble, 1246-1247 
sections, 1247-1248 
mapping files to memory, 
799-800 
mark-modified-lines variable 
(readline), 28 
mask bitmaps, creating from 
regular, 353-354 
masks, file-creation, 880 
setting, 45 
mattrib, 315-316, 330 
mbadblocks, 316, 330 
mblen, 977 
mbstowcs( ) function, 
977-978 
mbtowc( ) function, 978 
mcd, 316-317, 330 
mcookie, 317 
mcopy, 317-318, 330 
MD 5 message digests, 
generating/checking, 318 
md5sum, 318 
mdd, 318-319, 330 
mdedete (ftp command), 149 
mdaitree, 319 
mdir, 150, 319, 330 
mem, 1091-1092 
memccpy( ) function, 901, 
978-979 
memchr‘( ) function, 901, 979 
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memcmp( ) function 


memcmp( ) function, 901, 
979-980 
memcpy( ) function, 901, 980 
memfrob( ) function, 901, 
980-981 
memmen(( ) function, 901, 
981 
memmove{ ) function, 901, 
981 
memory 
access, controlling, 804-805 
allocating, 894, 976 
displaying amount, 144 
freeing, 976 
kernd, 1091-1092 
locking 
mlock, 796-797 
mlockall, 797-798 
mapping/unmapping files 
to, 799-800 
reallocating, 976 
scanning for characters, 979 
shared 
allocating, 851-853 
controlling, 849-851 
operations, 853-854 
system, 1091-1092 
unlocking 
munlock, 811-812 
munlockall, 812-813 
virtual 
renapping addresses 
805-806 
reports, 1417-1418 
virtual console, 1101-1102 
memory areas 
comparing, 979-980 
copying, 978-981 
encrypting, 980-981 
filling with constant bytes, 
982 
locating substrings in, 981 
memset( ) function, 901, 982 
merge, 320 
merge command (xauth), 591 
merging files, three-way, 320 
mesg, 321 


message catalogs 
getting messages from, 
902-903 
opening/closing, 903-904 
message queue identifier, 
retrieving, 807-808 
messages 
control, 1310 
control operations, 806-807 
displaying, 321 
log (RCS files), printing, 
458-460 
message of the day file, 1152 
receiving, from sockets, 
826-828 
sending/receiving, 808-811 
sending 
from sockets 842-843 
to system logger, 
1045-1046 
to users, 473, 576-577 
signal, printing, 996 
system console, monitoring 
with X, 597-598 
system error, printing, 
990-991 
systems, logging, 1404-1405 
Usenet control, handling, 
1115-1116 
writing to users, 574, 1383 
meta characters (bash), 12 
meta-flag variable (readline), 
28 
mformat, 321-322, 330 
bugs, 322 
options, 321-322 
mget (ftp command), 150 
MGR bitmaps, converting to 
portable bitmaps, 322-323 
mgrtopbm, 322-323 
MINIX filesystems, 1125 
consistency checker, 
1300-1301 
creating, 1326-1327 
mkdir, 150, 323, 794-795 
bugs, 795 
errors, 795 


options, 323 
return value, 795 
mkdirhier, 323 
mke2fs, 1324-1325 
mkfifo, 323-324, 982-983 
errors, 982-983 
options, 324 
mkfs, 1325-1327 
mklost+found, 1327 
mkmanifest, 324-325 
mknod, 325, 795-796 
bugs, 796 
errors, 796 
options, 325 
return value, 796 
mkstemp( ) function, 983 
mkswap, 1327-1328 
mktemp( ) function, 983-984 
mktime, 910, 984-986 
mlabel, 325-326, 330 
mlock, 796-797 
mlockall, 797-798 
mls (ftp command), 150 
mmap, 799-800 
mmd, 326, 330 
mmount, 326-327, 330 
mmove, 327, 330 
/mnt directory, 1236 
mode (ftp command), 150 
mode command (telnet), 508 
mode parameter, values, 1374 
modems, conversational 
exchanges, 1269-1273 
abort strings, 1270-1271 
chat script, 1270 
escape sequences, 
1271-1272 
report strings, 1271 
termination codes, 1272 
timeout value 1271 
moderators, 1151-1152 
modf( ) function, 984 
modify_Idt, 800 
modprobe, 109-112 
configuration, 110-111 
files, 111 
strategy, 111 


modtime (ftp command), 150 
modules 
kernd, loading at boot time, 
1152 
loadable 
support, 800-802 
unloading, 462-463 
viewing, 305 
more, 327-328 
motd, 1152 
mount, 802-804, 1328-1332 
bugs, 1332 
errors, 803 
files, 1332 
options, 1329-1331 
return value, 803 
mountd, 1332-1333 
mounting M S-D OS disks, 
326-327 
mouse, 1092-1094 
M icrosoft protocol, 1093 
MM protocol, 1094 
M ouseSystems protocol, 
1093 
Sun protocol, 1093 
mprotect, 804-805 
mput (ftp command), 150 
mrand48( ) functions, 912 
mrd, 329-330 
mread, 329 
mremap, 805-806 
mren, 329-330 
MS-DOS 
directories 
changing, 316-317 
displaying, 319 
trees ddding, 319 
disks, mounting, 326-327 
files 
changing attribute flags 
315-316 
copying to/from UNIX, 
317-318, 329 
ddding, 318-319 
displaying contents, 
333-334 
manipulating (mtoolg), 
330-333 


moving, 327 
rmaming, 329-330 
filesystems, adding to disks, 
321-322 
floppies, marking bad 
blocks, 316 
subdirectories 
creating, 326 
moving, 327 
removing, 329 
rmaming, 329-330 
volume labels, creating, 
325-326 
msdos filesystem, 1125 
msgctl, 806-807 
msgget, 807-808 
msgop, 808-811 
msync, 811 
mtest, 330 
mtools, 330-333, 1152-1158 
bugs, 333 
case sensitivity of VFAT, 
332 
character translation tables, 
1155-1157 
configuration files, testing, 
330 
default values, 1153 
drive geometry 
configuration, 1154-1155 
exit codes, 333 
general purpose drive 
variables, 1153-1154 
global variables, 1153 
long filenames, 331 
mattrib, 330 
mbadblocks, 330 
mcd, 330 
mcopy, 330 
mda, 330 
mdir, 330 
mformat, 330 
mlabd, 330 
mmd, 330 
mmount, 330 
mmove, 330 
mrd, 330 


mysnc 


mren, 330 
mtest, 330 
mtype, 330 
multiple descriptions, 1155 
name clashes, 332 
open flags, 1155 
parsing order of files, 
1157-1158 
per-drive flags/ variables, 
1153 
working directory, 331 
Xdf disks, 332 
MTV ray tracers, converting 
output to portable pixmaps, 
333 
mtvtoppm, 333 
mtype, 330, 333-334 
multilanguage support 
(description), 1243-1244 
multibyte characters, 
converting to wide 
characters, 978 
multibyte strings, converting 
to wide character, 977-978 
multiple buffers, reading/ 
writing data, 1003-1004 
multiuser chat program, 
727-730 
Boolean options, 729 
daemons, 727 
escape menu, 728 
readdressing, 729 
runtime options, 728-729 
startup file, 729 
username field, 727 
X11 interface, 730 
munchlist, 274, 279 
bugs, 282 
files, 281 
options, 279-280 
ge alm ispal 
munlock, 811-812 
munlockall, 812-813 
munmap, 799-800 
mv, 334-335 
mwrite, 335 
mysnc, 811 
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named 


named, 1334-1338 
boot file, 1334-1336 
files, 1337 
master file, 1336 
options, 1334 
signals, 1337 
SOA record, 1336-1337 
named pipes, see FIFOs 
named-xfer, 1333-1334 
named.reload, 1338 
named. restart, 1338 
named, 335-336 
options, 336 
output, 335 
names 
bash, 12 
peer, getting, 765 
socket, getting, 769 
nameserver (Internet 
domains), 1334-1338 
boot file, 1334-1336 
control interface, 1338-1339 
master file, 1336 
querying, 1350-1353 
signals, 1337 
SOA record, 1336-1337 
stopping/restarting, 1338 
synchronizing database, 
1338 
naming 
font servers, 643 
temporary files, 1049, 1054 
xhost, 644 
NaN (not-a-number) results 
returning value for, 954-955 
testing for, 959 
nanosleep, 813-814 
ncpfs filesystem, 1126 
ndc, 1338-1339 
N etnews reader, see tin 
snetrc file, 153-154 
netstat, 1339-1342 
files, 1341 
routing information, 1341 
socket information, 
1340-1341 


network byte order, convert- 
ing between host byte order, 
901-902 
network entries, getting, 
936-937 
networking 
displaying active 
connections, 1339-1342 
routing information, 1341 
socket information, 
1340-1341 
interfaces 
attaching to serial line 
1399 
configuring, 1304-1305 
routing daenon, 1380-1382 
newaliases, 336 
newer (ftp command), 150 
newgrp, 336-337 
news 
N etnews, setin 
news software information 
newsgroups, 530 
overview database 
expiring entries 
1293-1294 
format, 1168-1169 
updating, 1353-1354 
receiving from UUCP 
connections, 463-464 
news.daily, 1344-1346 
keywords, 1344-1345 
newsfeeds, 1158-1163 
Distribution headers, 1159 
entries, 1158-1159 
examples, 1162-1163 
feed types, 1161-1162 
flags, 1159-1161 
ME entry, 1161 
newsgroups 
news software information, 
530 
Usena, listing active, 1104- 
1105 
newslog, 1163-1165, 
1346-1347 
files, 1164 
keywords, 1346 
message/action fidds, 


1163-1164 
newsrequeue, 1342-1344 
NFS 

mount daemon, 1332-1333 
servers, authentication/print 

request, 1355-1357 

service daemon, 1347 
nfs, 1165-1167 
nfs filesystem, 1125 
export list, 1123-1125 
NFS servers, mount 
information, 1396 
nfsd, 1347 
nice, 814 
nl, 337-338 
nlist (ftp command), 150 
NLM outfiles, converting 
object code into, 338-339 
nimconv, 338-339 
nm, 339-340 
nmap (ftp command), 150 
nnrp.access, 1167-1168 
nnrpd, 1347-1349 
NNTP 
news, host list, 1132-1133 
servers, 1347-1349 
getting lists from, 206-207 
passwords 1170 
retrieving U se articles 
from, 340-341 
sites, access control, 

1167-1168 

NNTPcheckarticle routine, 
965 

NNTPconnect routine, 965 

nntpget, 340-341 

NNTPlocalopen routine, 965 

NNTPremoteopen routine, 
965 

nntpsend, 1349-1350 

nntpsend.ctl, 1168 

NNTPsendarticle routine, 966 

NNT Psendpassword routine, 
966 

NNTPSERVER environment 
variable, 529 


no_exit_on_failed_exec 
variable (bash), 18 
noclobber variable (bash), 18 
nolinks variable (bash), 18 
nologin, 1168 
none, 881 
none (undocumented library 
functions), 1060 
not-a-number (NaN) results 
returning value for, 954-955 
testing for, 959 
notify variable (bash), 17 
nrand48( ) functions, 912 
nroff 
emulating, 210-211 
output, filtering, 77 
nslookup, 1350-1353 
arguments, 1350 
commands, 1351-1353 
diagnostics, 1353 
environment, 1353 
files, 1353 
ntohl( ) function, 901-902 
ntohs( ) function, 901-902 
ntrans (ftp command), 
150-151 
null, 1094 
numbers 
floating-point 
absolute value 919 
converting to fractional/ 
integral components, 
927 
converting to strings 
913-914, 930-931 
pseudo-random, generating, 
912-913 
random, generating, 
1001-1002 
rounding, 1011-1012 
signs, copying, 907 
square roots, 1023 
numeric expressions, gtroff, 
239 


0 


objcopy, 341-342 
objdump, 342-343 
object files 
copying/translating, 
341-342 
discarding symbols from, 
499 
displaying information from, 
342-343 
listing section and total sizes, 
489-490 
listing symbols from, 
339-340 
oclock, 344 
od, 345-346 
offline printing, 299-301 
oldfstat, 814 
oldistat, 814 
oldolduname, 814 
OLDPWD variable (bash), 15 
oldstat, 814 
olduname, 814 
on_exit( ) function, 988 
open, 815-816 
bugs, 816 
erors, 816 
flags, 815 
ftp command, 151 
modes, 815 
return value, 816 
open host command (telnet), 
508 
opendir, 989 
openlog( ) function, 
1045-1046 
facility argument, 1046 
option argument, 1046 
operators 
awk, 166-167 
find, 142 
redirection, 21 
OPTARG variable (bash), 16 
OPTERR variable (bash), 17 
OPTIND variable (bash), 16 


papers formatting 


ORGANIZATION environ- 
ment variable, 529 
OSTYPE variable (bash), 16 
outb, 816 
outb_p, 816 
outl, 816 
outl_p, 816 
output 
formatting, 992-996, 
1022-1023 
conversion pecifiers 994 
examples, 995 
flags 993-994 
redirecting, 22 
output-meta variable 
(readline), 28 
outsb, 816 
outsl, 816 
outsw, 816 
outw, 816 
outw_p, 816 
overchan, 1353-1354 
overview.fmt, 1168-1169 
ownership (file), changing, 
62-63, 749-750 


P 


pac, 1354-1355 
packed format fonts, convert- 
ing to portable bitmaps, 381 
packets 
ECHO_REQUEST, 
sending, 1358 
route, printing, 1409-1412 
page size, system (getting), 
765 


paging 
disabling, 796-797 
calling process, 797-798 
remabling, 811-813 
papers, formatting 
groff_me macros, 
1225-1227 
groff_mm macros, 
1227-1234 
groff_ms macros, 
1234-1236 
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paragraphs, formatting linelength 


paragraphs, formatting line 
length, 143 
parameter command substitu- 
tion (bash), 20 
parameter expansion (bash), 
19-20 
parameters 
bash, 14-15 
postional, 14 
gedal, 14-15 
boot-time (kernel), 
1216-1224 
Adaptec configurations, 
1219-1220 
argument list, 1216-1217 
Bus ogic configuration, 
1220 
busnouse drivers 1224 
cards not accepting, 1220 
CD-ROMs 1222-1223 
debug argument, 1217 
Ethene devices, 1223 
floppy disk drives, 
1223-1224 
future domain 
configuration, 1220 
hard dixs, 1220-1221 
mem= argument, 1218 
no-hlit argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 
ramdisk= argument, 1218 
reboot=warm argument, 
1218 
reerve= argument, 
1217-1218 
ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI device arguments, 
1218-1219 
SCSI tape configuration, 
1219 
Seagate ST -0x 
configuration, 1220 


sound drivers 1224 
Trantor T 128 
configuration, 1220 
floppy disk, setting, 1391 
positional 
parsng, 38 
renaming, 42 
serial ports, 1392-1394 
parsedate, 989-990 
parser directives, readline, 
28-29 
$dse, 29 
gendif, 29 
Sif, 28-29 
parsing 
command options, 207-208 
command-line options, 
937-940 
positional parameters, 38 
partition tables, manipulat- 
ing, 1296-1297 
DOS 6.x, 1296-1297 
partitioning disk drives, 
1265-1269 
passwd, 346-347, 1169-1170 
bugs, 347 
files, 347 
passwd.nntp, 1170 
password files, editing, 
1418-1419 
passwords 
changing, 346-347 
encryption, 908-909 
file entries, writing, 997 
getting, 940-941 
getting file entry, 943-944 
password file 1169-1170 
reconstructing line entry, 
942-943 
paste, 347 
PATH variable (bash), 16 
pathconf( ) function, 925-926 
options returned, 926 
return value, 926 
pathname expansion (bash), 
21 


pathnames 
canonicalized absolute, 
1004-1005 
following to terminal point, 
335-336 
matching, 924, 949-950 
patterns 
printing lines matching, 
224-226 
searching database files for, 
295 
pause, 817 
pausing execution, 813-814 
pbm, 1170-1171 
PBM images, displaying on 
4425 terminals, 357 
pbmclean, 348 
pbmfilters, 348-352 
pbmlife, 352-353 
pbmmake, 353 
pbmmask, 353-354 
PBM Plus package, programs, 
348-352 
pbmpscale, 354 
pbmreduce, 355 
pbmtext, 355-356 
pbmto10x, 356 
pbmto4425, 357 
pbmtoascii, 357 
pbmtoatk, 358 
pbmtobg, 358 
pbmtocmuwm, 358-359 
pbmtoepsi, 359 
pbmtoepson, 359 
pbmtog3, 360 
pbmtogem, 360 
pbmtogo, 360-361 
pbmtoicon, 361 
pbmtolj, 361-362 
pbmtoin03, 362 
pbmtolps, 362 
pbmtomacp, 363 
pbmtomgr, 363 
pbmtopgm, 364 
pbmtopi3, 364 
pbmtopk, 364-365 


pbmtoplot, 365-366 
pbmtoptx, 366 
pbmtox10bm, 366 
pbmtoxbm, 367 
pbmtoybm, 367 
pbmtozinc, 367-368 
pbmupc, 368 
pclose{ ), 991-992 
penfsd, 1355-1357 
authentication, 1355-1356 
file, 1357 
printing, 1356 
reconfiguration, 1357 
PCX files, converting to 
portable pixmaps, 368-369 
pcxtoppm, 368-369 
peers, getting names, 765 
permissions 
file 
changing, 748-749 
gtting, 272-273 
port input/output, setting, 
788 
perror, 990-991 
personality, 817-818 
pfbtops, 369 
pgm, 1171-1172 
pgmbentley, 369 
pgmcrater, 370-371 
pgmedge, 371 
pgmenhance, 371-372 
pgmhist, 372 
pgmkernd, 372-373 
pgmnoise, 373 
pgmnorm, 373-374 
pgmoil, 374 
pgmramp, 374-375 
pgmtexture, 375-376 
pgmtofs, 376 
pgmtolispm, 376-377 
pgmtopbm, 377 
pgmtoppm, 378 
Photo-C D files, converting to 
portable pixmaps, 260-261 
phys, 818 
physical addresses, accessing, 
818 


pi3topbm, 379 
pic, versus gpic, 212-215 
commands, 212-213 
expressions, 213-214 
mode, 212 
picttoppm, 379-380 
bugs, 379 
fontdir file format, 380 
ping, 1358 
pipe, 818-819 
pipelines (|), bash, 12 
pipes, creating, 818-819 
pjtoppm, 381 
pktopbm, 381 
PLIP devices, tuning 
parameters, 1357 
plipconfig, 1357 
pnm, 1173 
pnmalias, 381-382 
pnmarith, 382-383 
pnmcat, 383 
pnmcomp, 383-384 
pnmconvol, 384 
pnmcrop, 385 
pnmcut, 385 
pnmdepth, 385-386 
pnmenlarge, 386 
pnmfile, 386-387 
pnmflip, 387 
pnmgamma, 387 
pnmhistmap, 388 
pnmindex, 388-389 
pnminvert, 389 
pnmmargin, 389-390 
pnmnifilt, 390-391 
alpha-trimmed mean filter, 
390 
bugs, 391 
combining modes, 391 
edge enhancement, 391 
optimal estimation 
smoothing, 390 
pnmnoraw, 391-392 
pnmpad, 392 
pnmpaste, 392-393 
pnmrotate, 393 
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pnmscale, 393-394 
pnmshear, 394-395 
pnmsmooth, 395 
pnmtile, 395 
pnmtoddif, 396 
pnmtofits, 396-397 
pnmtoiff, 399-400 
pnmtops, 397 
pnmtorast, 398 
pnmtosgi, 398-399 
pnmtosir, 399 
pnmtoxwd, 400 
popd (shell command), 39-40 
popen( ) function, 991-992 
popup-menu( ) action 
(xterm), 713 
port, 1091-1092 
portable anymaps 
antialiasing, 381-382 
bordering, 389-392 
changing maxval, 385-386 
compositing, 383-384 
concatenating, 383 
converting 
to DDIF format, 396 
to FITS format, 396-397 
to PostScript, 397 
to red/blue 3D glasses, 
400-401 
to SGI image file 
398-399 
to Solitaire format, 399 
to Sun rater files, 398 
to TIFF files, 399, 400 
to X11 window dumps 
400 
convolving, 384 
creating index of, 388, 389 
cropping, 385 
cutting rectangles from, 385 
describing, 386, 387 
drawing histograms from, 
388 
enlarging, 386 
file format, 1173 
flipping, 387 
gamma correction, 387 
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portable anymaps 


inverting, 389 
pasting rectangles into, 392, 
393 
performing arithmetic on, 
382, 383 
plain format, 391, 392 
programs 
constants, 970 
format promotion, 972 
functions supporting, 970, 
971, 972 
initialization, 971 
memory management, 971 
reading files, 971 
types, 970 
writing files, 971, 972 
XEL manipulations, 
971-972 
replicating into specified 
size, 395 
rotating, 393 
scaling, 393, 394 
shearing, 394, 395 
smoothing, 395 


portable bitmaps 


applying Rules of Life to, 
352, 353 
converting 

to Andrew T oolkit raster 
objects, 358 

to ASCII graphics, 357 

to Atari D egasP 13 files, 
364 

to Bennet Y ee “face” files, 
367 

to BitGraph graphics, 358 

to CMU window manager 
bitmaps 358-359 

to compressed GraphO n 
graphics 360-361 

to DEC LN 03+ Sixa 
output, 362 

to encapsulated P otScript- 
gyle bitmaps 359 

to Epson printer graphics, 
359 


toGEM IMG files, 360 
to Gemini 10x graphics, 
356 
to Group 3 fax files 360 
to HP Las & format, 
361-362 
to M acPaint files 363 
to MGR bitmap, 363 
to packed format fonts, 
364-365 
to portable graymaps, 364 
to PostScript, 362 
to Printronix printer 
graphics 366 
to Sun icons, 361 
to UNIX plot file, 
365-366 
to X10 bitmaps 366 
to X11 bitmaps 367 
to Zinc bitmaps, 367-368 
creating with specified size, 
353 
enlarging, 354 
file format, 1170-1171 
flipping pixdsin, 348 
programs 
consants, 968 
endian i/o, 967 
errors, 967 
filemanagement, 967 
functions supporting, 
966-969 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 
reading files 968 
types, 968 
writing files 968-969 
reducing, 355 


portable graymaps 


Bentleyizing, 369 

calculating textural features 
on, 375-376 

combining three into a 
portable pixmap, 457-458 


converting 
to Lisp machine format, 
376-377 
to portable bitmaps 377 
to portable pixmaps, 378 
to U senix FaceSaver 
format, 376 
creating from white noise, 
373 
enhancing edges, 371-372 
file format, 1171-1172 
mimicking cratered terrain, 
370-371 
normalizing contrast, 
373-374 
outlining edges, 371 
performing oil transfers on, 
374 
printing histogram of values, 
372 


programs 
congants, 969 
functions supporting, 

969-970 

initialization, 969 
memory managenent, 969 
reading files 970 
types, 969 
writing files 970 


portable pixmaps 


blending together, 408-409 
brightening, 404 
changing pixel color, 
401-402 
changing saturation and 
value, 401 
converting 
to Abekas YU V files, 428 
to Atari D egasP!1 files, 
422 
to AutoCAD, 414-416 
to BMP files, 416 
to DEC axe format, 
425-426 
to GIF files 416-417 
toHP PaintJe file, 423 


to HP Paintjet XL PCL 
files, 424 
tolLBM files, 418-419 
to Macintosh PICT files, 
422-423 
Mitsubishi $340-10 
files 420-421 
to M otifUIL icon files 
427 
to N CSA ICR format, 
417-418 
to PCX files 421 
to portable graymaps, 
421-422 
to three portable graymaps, 
425 
to threeraw YUV file, 
428-429 
to TrueVision T arga files 
426 
to X11 pixmaps, 427-428 
to X11 puzzle files, 
424-425 
creating, 408 
patterns 410-411 
specifying color, 408 
creating from three portable 
graymaps, 457-458 
dimming 
to black, 402 
every other row, 409-410 
displacing pixels, 414 
dithering, 403 
extracting color from, 
419-420 
file format, 1173-1174 
files 
reading, 974 
writing, 974 
fractal forgeries, 404-407 
grayscale assignments 
(performing), 402-403 
histograms (printing), 408 
Laplacian relief filters 
(running on), 413 
normalizing contrast, 409 


t 


Oo 





programs, functions 
supporting, 973-974 
quantizing colors, 411 
8-plane quantization, 
412-413 
multiple files 412 
shifting lines, 413-414 
portmap, 1358-1359 
ports 
input/output functions, 816 
input/output permissions, 
setting, 788 
serial 
configuring, 1394-1395 
parameters, 1392-1394 
satting/getting informa- 
tion, 1391-1395 
system, 1091-1092 
positional parameters 
bash, 14 
parsing, 38 
renaming, 42 
POSIX 
gawk compatibility, 171 
regex functions, 1005-1007 
compiling, 1005-1006 
error reporting, 1006 
matching, 1006 
pattern buffer freeing, 
1007 
signal set operations, 
1019-1020 
PostScript 
bounding box, extracting, 
433 
files, converting to portable 
anymaps, 434-435 
fonts 
trandating from PFB 
format to ASCII, 369 
trandating fromP FB 
format to ASCII, 369 
image data, converting into 
portable graymap, 
433-434 
pound sign (#) 
bash comments, 14 
bash special parameters, 15 


ppmtoxpm 


pow( ) function, 918 
powerd, 1359-1360 
powers (raising numbers to), 
918 

PPID variable (bash), 15 
ppm, 1173-1174 
ppm3d, 400-401 
ppmbrighten, 401 
ppmchange, 401-402 
ppmdim, 402 
ppmdist, 402-403 
ppmdither, 403 
ppmflash, 404 
ppmforge, 404-407 

bugs, 407 

options, 405-407 
ppmhist, 408 
ppmmake, 408 
ppmmix, 408-409 
ppmnorm, 409 
ppmnitsc, 409-410 
ppmpat, 410-411 
ppmquant, 411-412 
ppmquantall, 412 
ppmaqvga, 412-413 
ppmrelief, 413 
ppmshift, 413-414 
ppmogpread, 414 
ppmtoacad, 414-416 
ppmtobmp, 416 
ppmtogif, 416-417 
ppmtoicr, 417-418 
ppmtoilbm, 418-419 
ppmtomap, 419-420 
ppmtomitsu, 420-421 
ppmtopcx, 421 
ppmtopgm, 421-422 
ppmtopil, 422 
ppmtopict, 422-423 
ppmtopj, 423 
ppmtopjxl, 424 
ppmtopuzz, 424-425 
ppmtorgb3, 425 
ppmtosixel, 425-426 
ppmtotga, 426 
ppmtouil, 427 
ppmtoxpm, 427-428 
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ppmtoyuv 


ppmtoyuv, 428 
ppmtoyuvsplit, 428-429 
PPP 
daemon, 1360-1369 
statistics, printing, 
1369-1370 
pppd, 1360-1369 
authentication, 1366-1367 
diagnostics, 1368 
examples, 1367-1368 
files, 1366-1369 
options, 1360-1366 
routing, 1367 
signals, 1369 
pppstats, 1369-1370 
pr, 429-430 
preprocessor, 81-84 
preprocessors, imake, 264-267 
printf function, 992-996 
bugs, 995-996 
printf statement, awk, 
167-168 
printing 
aliases, 35 
application resources, 5 
banners, 1210 
converting text files for, 
429-430 
files, in reverse, 503-504 
histograms of portable 
pixmaps, 408 
host ID s, 258-259 
lines matching a pattern, 
224-226 
log messages (RCS files), 
458-460 
machine architecture, 8 
offline, 299-301 
packet route, 1409-1412 
pcnfsd, 1356 
PPP statistics, 1369-1370 
printer/plotter accounting 
files (reading), 1354-1355 
removing jobs from queue, 
301-302 
ripple test pattern, 302 
signal messages, 996 


spool queue examination, 
298-299 
system activity summary, 
573 
system error messages, 
990-991 
time zones, 1419 
user/system times, 43 
ge alm line printer 
priority values, getting range, 
830-831 
privileges 
1/0, changing level, 
788-789 
setuid (RCS files), 67-68 
/proc, 1174-1180, 1236 
bugs, 1180 
hierarchy outline, 1174- 
1180 
proc filesystem, 1125 
proc_sel, 1430-1431 
process control, initialization, 
1307-1309, 1397-1399 
process groups, sending 
signals to, 790-791, 960 
process substitution (bash), 
20 
processes 
0, making idle 774 
accounting, switching on/ 
off, 742 
child, creating, 751, 758 
closing, pclose{ ) function, 
991-992 
displaying tree of, 435-436 
execution, suspending, 1061 
execution domain, setting, 
817-818 
group identity, setting, 845 
group IDs 
gatting/setting, 845-846 
real and effective (setting), 
846-847 
groups 
access lists (getting/sating), 
761-762 
ID s(getting), 761 


identifying, 154-155 
IDs, getting, 766 
listing most C PU -intensive, 
533-535 
opening, popen( ) function, 
991-992 
parents, IDs (getting), 766 
priorities, altering, 
1375-1376 
priority, changing, 814 
reporting status, 430-433 
SCH ED_RR interval, 
getting, 831 
scheduling priorities, 
getting/setting, 766-767 
selecting, by criteria, 
1430-1431 
sending signals to, 790 
raise function, 1000 
starting, on consoles, 1066 
terminating, 283-284, 
739-740 
by name 284 
times, getting, 878-879 
tracing, 820 
user 1D s 
getting, 773 
real and effective (setting), 
847-848 
sting, 848-849 
waiting for termination, 
886-889 
yielding processor, 835 
processor, time used (deter- 
mining), 905 
profil, 819 
profiling, 819 
programs 
executing, 754-755 
portable anymap 
congants, 970 
format promotion, 972 
functions supporting, 
970-972 
initialization, 971 
memory management, 971 
reading files 971 


types, 970 
writing files, 971-972 
XEL manipulations, 
971-972 
portable bitmap, functions 
supporting, 966-969 
portable graymap 
constants, 969 
functions supporting, 
969-970 
initialization, 969 
memory management, 969 
reading files, 970 
types, 969 
writing files, 970 
recompiling, make utility, 
310-312 
running, in new session, 
1395 
terminating 
abort( ) function, 892 
asert( ) function, 
895-896 
exit() function, 917 
promoting directories, 39-40 
prompt (ftp command), 151 
PROMPT_COMMAND 
variable (bash), 17 
prompting (bash), 26 
properties, consoles, 1067 
protocols 
protocols definition file, 
1180-1181 
RPC, rpcgen compiler, 
464-466 
Teln4, interface, 507-512 
XIE, testing, 645-654 
proxy ftp (ftp command), 151 
proxy servers, LBX, 286-287 
PRT ray tracers, converting 
output to portable pixmaps, 
333 
prunehistory, 1370-1371 
ps, 430-433 
bugs, 433 
fidd descriptions, 432 
options, 430-431 


sort keys, 431-432 

updating, 432, 436 
PS1 variable (bash), 16 
PS2 variable (bash), 16 
PS3 variable (bash), 17 
PS4 variable (bash), 17 
psbb, 433 
pseudo-filesystems, /proc, 

1174-1180 
bugs, 1180 
hierarchy outline, 
1174-1180 
pseudo-random numbers, 
generating, 912-913 

psidtopgm, 433-434 
pstopnm, 434-435 
pstree, 435-436 
psupdate, 436 
ptrace, 820 
pushd (shell command), 40 
put (ftp command), 151 
put_file_last, 1431 
putc( ) function, 997-999 
putchar( ) function, 997-999 
putenv, 996-997 

errors, 996 
putpwent( ) function, 997 

errors, 997 
puts( ) function, 997-999 
pututline( ) function, 948 
putw function, 948 
pwd (ftp command), 151 
pwd (shell command), 40 
PWD variable (bash), 15 


Q 


qio, 998 
QRT ray tracer, converting 
output to portable pixmaps, 
436-437 
qsort, 1000 
quantizing colors (pixmaps), 
411 
8-plane quantization, 
412-413 
multiple files, 412 


rawtoppm 


question marks (?) 
bash special parameters, 15 
ftp command, 152 
queues, inserting/removing 
items, 957 
quit command 
ftp command, 151 
telnet, 508 
xauth, 591 
quit( ) action (xterm), 714 
quota, 437 
quotacheck, 1371-1372 
quotactl, 821-822 
quotaoff, 1372-1373 
quotaon, 1372-1373 
quotas 
disk, manipulating, 821-822 
remote machines, 1012 
quote (ftp command), 151 
quoting (bash), 14 


R 


Radix32 routine, 966 

raise function, 1000 

ram, 1094-1095 

rand( ) function, 1001 

random numbers, generating, 
1001-1002 

RANDOM variable (bash), 15 

random( ) function, 
1001-1002 

randomizing strings, 1032 

ranlib, 437-438 

rarp, 1373 

RARP table, manipulating, 
1373 

rasttopnm, 438 

raw grayscale bytes, convert- 
ing to portable graymaps, 
439 

raw RGB bytes, converting to 
portable pixmaps, 439-440 

rawtopgm, 439 

rawtoppm, 439-440 
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ray traces 


ray tracers 
converting output to 
portable pixmaps, 333 
QRT, converting output to 
portable pixmaps, 436-437 
rcp, 440-441 
RCS (Revision Control 
System), 447-449 
automatic identification, 
449 
commands, 447-449 
directories, creating, 
447-449 
files 
changing attributes, 
441-443 
cleaning, 443-445 
comparing revisions, 
445-446 
freezing configuration, 
446-447 
functions, 447 
revisions, merging, 449-451 
rcs, 441-443 
bugs, 443 
compatibility, 443 
diagnostics, 443 
environment, 443 
files, 443 
options, 441-443 
RCS files 
controlling access, 67 
format, 1181-1183 
modes, 67 
organization (diagram), 
1182 
printing log messages, 
458-460 
retrieving revisions, 71-75 
specifying, 66-67 
storing revisions, 64-69 
stuid privileges, 67-68 
temporary files, 67 
RCS keyword strings, 
identifying, 262-263 
RCSBIN environment 
variable, 105 


rcsclean, 443-445 
rcsdiff, 445-446 
rcsfile, 1181-1183 
organization (diagram), 
1182 
rcsfreeze, 446-447 
rcsintro, 447-449 
automatic identification, 
449 
RCS functions, 447 
rcsmerge, 449-451 
rdev, 1373-1375 
rdiff (cvs command), 101 
rdist, 451-454 
bugs, 454 
diagnostics, 454 
files, 453 
options, 451-452 
re_comp function, 1005 
re_exec function, 1005 
read (shell command), 40 
read( ), file descriptors, 822 
readdir, 823 
readdir( ) calls, setting 
position, 1015-1016 
readdir( ) function, 
1002-1003 
ReadInD escriptor routine, 
966 
ReadIinFile routine, 966 
readline library, 27-32 
commands, 29-32 
controlling key bindings, 27 
customizing, 27 
denoting keystrokes, 27 
macro definitions, 28 
parser directives, 28-29 
$dse 29 
$endif, 29 
$if, 28-29 
variables, 28 
bdl-dyle 28 
comment-begin, 28 
completion-query- items, 
28 
convert-meta, 28 
editing-mode 28 
expand-tilde, 28 


horizontal-scroll-mode 28 
keymap, 28 
mark-modified-lines, 28 
mea-flag, 28 
output-méa, 28 
ow-all-if-ambiguous 28 
readlink, 823-824 
readonly (shell command), 40 
readv, 824-825 
readv( ) function, 1003-1004 
realloc( ) function, 976-977 
realpath, 1004-1005 
reboot, 825-826 
recompiling programs, make 
utility, 310-312 
recompressing Z files, 
734-735 
reconfig, 454 
recv, 151, 826-828 
recvfrom, 826-828 
recvmsg, 826-828 
redirection, 21-23 
duplicating file descriptors, 
23 
here-documents, 22-23 
input, 22 
opening file descriptors, 23 
operators, 21 
output, 22 
redraw( ) action (xterm), 714 
ref, 455-456 
edlvis interaction, 455 
environment, 455 
files, 455 
options, 455 
search method, 455 
refreshing screen (X), 684-685 
refs files, generating, 87-88 
regcomp function, 1005-1007 
regerror function, 1005-1007 
reget (ftp command), 151 
regex functions, 1005 
POSIX, 1005-1007 
compiling, 1005-1006 
error reporting, 1006 
matching, 1006 
pattern buffer freeing, 
1007 


regexec function, 1005-1007 
regfree function, 1005-1007 
regular expressions 
grep, 225-226 
sed, 476-477 
release (cvs command), 101 
remote execution server, 
1376-1377 
remote file copying, 440-441 
remote logging, 1403 
remote login server, 
1377-1378 
remote logins, 460-461 
Kerberos authentication, 
461 
remote machines, starting X 
programs on, 676 
remote quota server, 1384 
remote shell, 466-467 
remote shell server, 
1385-1386 
Remote Start client, see rstart 
Remote Start rsh helper, see 
rstartd 
remote status, displaying, 472 
remote systems, command 
execution, 569-571 
remote user communication 
server, 1405-1406 
remotehelp (ftp command), 
151 
remotestatus (ftp command), 
151 
remove, 1008 
cvs command, 101-102 
xauth command, 591 
remove file free, 1431-1432 
remque{ ) function, 957 
rename, 828-829 
rename (ftp command), 151 
renice, 1375-1376 
REPLY variable (bash), 15 
REPLYTO environment 
variable, 529 
repquota, 1376 
res init, 1008-1011 


res mkquery, 1008-1011 
res query, 1008-1011 
res _search, 1008-1011 
res_ send, 1008-1011 
reserved words (bash), 12 
reset, 456, 539-542 
compatibility, 542 
options, 540 
setting environment, 540 
terminal type mapping, 
540-541 
reset (ftp command), 151 
resize, 456-457 
resolver, 1183-1184 
resolver routines, 1008-1011 
resolving hostnames, 
1238-1239 
resource editor, see editres 
resources 
limits, getting/setting, 
767-768 
usage, getting, 767-768 
restart (ftp command), 151 
return (shell command), 40 
return value, errors, 797 
rev, 457 
reverse line feeds, filtering, 76 
Revision Control System, see 
RCS 
rewind function, 927-928 
rewinddir( ) function, 1011 
rexecd, 1376-1377 
bugs, 1377 
diagnostics, 1377 
protocol, 1376-1377 
RGB colorname databases, 
uncompiling, 488 
rgb3toppm, 457-458 
rindex( ) function, 953 
rint( ) function, 1011-1012 
ripple test pattern (printing), 
302 
rlog, 458-460 
rlogin, 460-461 
rlogind, 1377-1378 
rm, 461-462 


routines 


rmdir, 462, 829-830 
bugs, 830 
errors, 829 
options, 462 
rmdir (ftp command), 152 
rmmod, 462-463 
rnews, 463-464 
Rock Ridge filesystem, 1125 
root logins, tty lines (listing), 
1184 
root directories 
changing, 750-751, 1273 
root filesystem, mounting, 
849 
root window (X), setting 
parameters, 693-694 
round-robin scheduling, 834 
rounding integers, 904 
rounding numbers, 
1011-1012 
route, 1379-1380 
routed, 1380-1382 
bugs, 1382 
files, 1382 
gateways, 1381-1382 
options, 1381 
request packets, 1381 
response packets, 1381 
starting, 1380 
routines 
ICCcancd, 956 
ICCclose, 956 
ICC command, 956 
ICCgo, 956 
ICCopen, 956 
ICCpause, 956 
ICCreserve, 956 
IC Csettimeout, 956 
libinn library, 962-966 
CAdos, 964 
CAlistopen, 964 
CAopa, 964 
CloseO nE xec, 965 
DD check, 965 
DDend, 965 
DD art, 965 
GaConfigValue 965 
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routines 


GaF ileC onfigValue, 965 

GeaFQDN, 965 

GetM oderatorAddress, 
965 

GetResource sage 965 

GaT imdnfo, 965 

H eaderFind, 964 

INN Version, 966 

LockFile 965 

NNT Pcheckartide 965 

NNT Pconnect, 965 

NNT Plocalopen, 965 

N 

N 


=a 


NT Premoteopn, 965 
NT Psendarticle 966 
NNT Psendpassword, 966 
Radix32, 966 

ReadinD exriptor, 966 
ReadinFile 966 

SAN onBlocking, 965 
libpbm, 966-969 

consants, 968 

endian i/o, 967 

errors, 967 
filemanagement, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 

reading files, 968 

types, 968 

writing files, 968-969 
libpgm, 969-970 

constants, 969 
initialization, 969 
memory management, 969 
reading files, 970 

types, 969 

writing files, 970 
libpnm, 970-972 

constants, 970 

format promotion, 972 
initialization, 971 
memory management, 971 
reading files, 971 

types, 970 

writing files, 971-972 
XEL manipulation, 972 
XEL manipulations, 971 











routing, pppd, 1367 
RPC 


program numbers, 
converting to DARPA port 
numbers, 1358-1359 
protocol compiler, se rpcgen 
services, reporting informa- 
tion, 1383-1384 
rpc.rquotad, 1384 
rpc.rusersd, 1382-1383 
rpc.rwalld, 1383 
rpcgen, 464-466 
options, 465-466 
preprocessor symbols, 465 
rpcinfo, 1383-1384 
rquota( ) protocol, 1012 
rquotad, 1384 
rsh, 466-467 
rshd, 1385-1386 
rstart, 467-468 
rstartd, 468-471 
configuring, 469 
keywords, 470 
installing, 469 
options, 469 
rtag (cvs command), 102 
runique (ftp command), 152 
rup, 472 
rusers, 472-473 
rwall, 473 
rwho, 474 
rwhod, 1386-1387 


S 


saving stack context, 1018 
/sbin directory, 1237 
sbrk, 746 
scandir( ) function, 
1012-1013 
scanf functions, 1013-1015 
bugs, 1015 
conversions, 1014-1015 
flags, 1014 
return values, 1015 
sched_get_priority_max, 
830-831 


sched_get_priority_min, 
830-831 
sched_getparam, 832 
sched_getscheduler, 833-835 
errors, 834 
policies, 833 
SCHED_FIFO, 833-834 
SCHED_OTHER, 834 
SCHED_RR, 834 
response time, 834 
sched_rr_get_interval, 831 
sched_setparam, 832 
sched_setscheduler, 833-835 
errors, 834 
policies, 833 
SCHED_FIFO, 833-834 
SCHED_OTHER, 834 
SCHED_RR, 834 
response time, 834 
sched_yield, 835 
scheduling 
algorithm, getting/setting, 
833-835 
parameters, getting/setting, 
832 
policies, 833 
first in - first out, 
833-834 
round-robin, 834 
time sharing, 834 
priorities 
getting/setting, 766-767 
value ranges, 830-831 
yielding processor, 835 
screen, clearing, 70-71 
screen savers, beforelight, 
47-48 
script, 474-475 
scripts, chat, 1270 
scroll-back( ) action (xterm), 
714 
scroll-forw( ) action (xterm), 
714 
SCSI drivers 
disk drives, 1095-1096 
tape devices, 1096-1100 
sd, 1095-1096 


searching 
binary trees, 1056 
strings, for character sets, 
1035-1039 
second extended filesystems 
creating, 1324-1325 
lost+found directory, 1327 
tunable parameters 
(adjusting), 1412-1413 
SECONDS variable (bash), 15 
secure( ) action (xterm), 713 
securetty, 1184 
security 
sysklogd, 1403-1404 
X server, 688-689 
xterm, 712 
sed, 475-480 
addresses, 476 
bugs, 480 
commands, 478-479 
grouping, 478 
gyntax, 476 
comments, 477 
diagnostics, 479-480 
options, 475 
regular expressions, 476-477 
replacement pattern 
symbols, 477 
search pattern symbols, 
476-477 
seed48( ) functions, 912 
seekdir( ) function, 
1015-1016 
select, 835-837 
select-cursor-end action 
(xterm), 714 
select-cursor-start( ) action 
(xterm), 714 
select-end( ) action (xterm), 
714 
select-extend( ) action 
(xterm), 714 
select-start( ) action (xterm), 
714 
selections, copying into cut 
buffers, 598-599 


semaphore sets 
control operations, 837-839 
GETALL, 838 
GETNCNT, 838 
GETPID, 838 
GETVAL, 838 
GETZCNT, 838 
IPC_RMID, 838 
IPC_SET, 838 
IPC_STAT, 837 
SETALL, 838 
SETVAL, 838 
identifiers (getting), 
839-840 
operations, 840-842 
semctl, 837-839 
errors, 838-839 
operations, 837-838 
GETALL, 838 
GETNCNT, 838 
GETPID, 838 
GET VAL, 838 
GETZCNT, 838 
IPC_RMID, 838 
IPC_SET, 838 
IPC_STAT, 837 
SETALL, 838 
SETVAL, 838 
semget, 839-840 
semop, 840-842 
send, 842-843 
ftp command, 152 
send arguments command 
(telnet), 508-509 
send-signal( ) action (xterm), 
714 
sendmail, 1387-1390 
aliases, 1390 
exit status codes, 1390 
files, 1390 
flags, 1388 
options, 1389-1390 
sendmsg, 842-843 
sendport (ftp command), 152 
sendto, 842-843 
serial lines 
monitoring, 1359-1360 
network interfaces, 
attaching, 1399-1401 


servers 


serial mouse interface, 
1092-1094 
M icrosoft protocol, 1093 
MM protocol, 1094 
M ouseSystems protocol, 
1093 
Sun protocol, 1093 
serial ports 
configuring, 1394-1395 
parameters, 1392-1394 
setting/getting information, 
1391-1395 
serial terminal lines, 1101 
servers 
biff, 1274-1275 
controlling with xdm, 
612-613 
DARPA FTP, 1301-1304 
requests supported, 
1302-1303 
DARPA T dine protocol, 
1406-1407 
DARPA TFTP, 1407 
domain 
looking up hostnames 
with, 257-258 
resolver routines 
1008-1011 
font (X) 
displaying information 
about, 145 
generating BD F fonts 
146-147 
listing fonts 145-146 
interned atoms, listing, 
668-669 
Internet, xinetd (starting 
with), 655-664 
Internet domain nameserver, 
1334-1338 
boot file 1334-1336 
control interface, 
1338-1339 
maser file 1336 
querying, 1350-1353 
ggnals 1337 
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SOA record, 1336-1337 
gopping/retarting, 1338 
gynchronizing databas, 
1338 
Internet superserver, 
1305-1307 
LBX proxy server, 286-287 
logged-in users, 1382-1383 
news, sending U senet 
articles to, 267-269 
NFS 
authentication/print 
request, 1355-1357 
mount information, 1396 
NNTP, 1347-1349 
getting lits from, 206-207 
passwords 1170 
rérieving U ene artides 
from, 340-341 
portmap, 1358-1359 
remote execution, 
1376-1377 
remote login, 1377-1378 
remote quota, 1384 
remote shal, 1385-1386 
remote user communication, 
1405-1406 
specifying, xdm, 607-608 
system status, 1386-1387 
message format, 
1386-1387 
X Window System 
access control program, 
643-645 
display server, 685-690 
file utility, 587-592 
font server, 641-643 
information utility, 614 
killing dients 666-667 
garting, 664-666 
virtual framebuffer, 
717-718 
X11 
performance comparison 
program, 585-586 
performance test program, 
577-585 


XF86_ 8514, 615 
XF86_Accel, 614-623 
configuration, 615-616 
files, 622 
options, 616 
gtup, 616-622 
XF86_AGX, 615 
XF86_M ach32, 615 
XF86_M ach64, 615 
XF86_M ach8, 615 
XF86_M ono, 624-627 
configuration, 624 
files, 626 
setup, 624-626 
XF86_P9000, 615 
XF86_S3, 615 
XF86_SVGA, 627-631 
configuration, 627-628 
files, 630-631 
options, 628 
stup, 628-630 
XF86_VGA16, 631-633 
configuration, 631 
files, 633 
options, 632 
gtup, 632 
XF86_W 32, 615 
XFree86, 636-641 
configuration, 636 
environment variables 
637 
files, 638-639 
key combinations 638 
nework connections, 
636-637 
options, 637-638 
stup, 638 
services, 1184-1186 
bugs, 1186 
files, 1186 
Internet, listing, 1184-1186 
NFS, daemon, 1347 
RPC, reporting information, 
1383-1384 
Session M anager Proxy, see 
smproxy 


sessions 
creating, setsid, 848 
IDs, getting, 768 
typescripts, creating, 
474-475 
X Session M anager, 694-698 
default startup applica- 
tions 695 
options, 695-698 
proxy, 698 
remote applications 698 
Sesion menu, 695-696 
SM_SAVE_DIR 
environment variable 
695 
garting, 695 
tester, 698-699 
xeon file 695 
xdm, 600 
sessreg, 480-481 
set 
shell command, 40-42 
telnet command, 509-510 
set-allow132( ) action (xterm), 
715 
set-altscreen( ) action (xterm), 
715 
set-appcursor( ) action 
(xterm), 715 
set-appkeypad( ) action 
(xterm), 715 
set-autolinefeed( ) action 
(xterm), 715 
set-autowrap( ) action 
(xterm), 715 
set-cursesemul( ) action 
(xterm), 715 
set-jumpscroll( ) action 
(xterm), 715 
set-marginbell( ) action 
(xterm), 715 
set-reverse-video( ) action 
(xterm), 715 
set-reversewrap( ) action 
(xterm), 715 
set-scroll-on-key( ) action 
(xterm), 715 


set-scroll-on-tty-output( ) 
action (xterm), 715 
set-scrollbar( ) action (xterm), 
715 
set-tek-text( ) action (xterm), 
715 
set-terminal-type{ ) action 
(xterm), 715 
set-visibility( ) action (xterm), 
715 
set-visual-bell( ) action 
(xterm), 715 
set-vt-font( ) action (xterm), 
714 
setbuf function, 1016-1017 
setbuffer function, 1016-1017 
setdomainname, 760 
setegid, 846-847 
setenv( ) function, 1017 
seteuid, 847-848 
setfdprm, 1391 
setfsgid, 843-844 
setfsuid, 844 
setgid, 845 
setgrent( ) function, 932-933 
setgroups, 761-762 
sethostid, 762-763 
sethostname, 763 
setitimer, 763-764 
bugs, 764 
defining values, 764 
errors, 764 
return value, 764 
timer types, 764 
setjmp( ) function, 1018 
setlinebuf function, 
1016-1017 
setlocale{ ) function, 
1018-1019 
setmntent( ) function, 
935-936 
SetN onBlocking routine, 965 
setpgid, 845-846 
setpgrp, 845-846 
setpriority, 766-767 
setprotoent( ) function, 
941-942 


setpwent( ) function, 943 
setregid, 846-847 
setreuid, 847-848 
setrlimit, 767-768 
setserial, 1391-1395 
configuration consider- 
ations, 1394-1395 
files, 1395 
options, 1392 
parameters, 1392-1394 
setservent( ) function, 946 
setsid, 848, 1395 
errors, 848 
setsockopt, 769-772 
bugs, 772 
errors, 771 
options recognized, 770-771 
SO_BROADCAST, 771 
SO_DEBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO_KEEPALIVE, 770 
SO_LINGER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIMEO, 771 
SO_REUSEADDR, 770 
SO_SNDBUF, 771 
SO_SNDLOWAT, 771 
SO_SNDTIMEO, 771 
SO_TYPE, 771 
return value, 771 
setstate{ ) function, 
1001-1002 
setterm, 482-483 
settimeofday, 772-773 
setuid, 848-849 
setup, 849 
setusershell( ) function, 
946-947 
setutent( ) function, 947 
setvbuf function, 1016-1017 
SGI image files, converting to 
portable anymaps, 483-484 
sgitopnm, 483-484 
sh, expansion, 19 
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shadow directories (creating), 
294 
shar, 484-487 
files, unpacking, 560-561 
options, 484-486 
shared libraries, selecting, 883 
shared memory 
allocating, 851-853 
controlling, 849-851 
commands, 850 
gysten calls, 851 
operations, 853-854 
shell variables (bash), 15-18 
allow-null_glob_ expansion, 
17 
auto_resume, 18 
BASH, 15 
BASH _VERSION, 15 
cdable_vars, 18 
CDPATH, 16 
command_oriented_history, 
17 
ENV, 16 
EVID, 15 
FCEDIT, 17 
FIGNORE, 17 
glob_dot_filenames, 17 
histchars, 17-18 
HISTCMD, 16 
HISTFILE, 17 
HISTFILESIZE, 17 
history control, 17 
HISTSIZE, 17 
HOME, 16 
hostname_completion_file 
18 
HOSTTYPE, 16 
IFS, 16 
IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 
MAIL_WARNING, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_exit_on_failed_exec, 18 
noclobber, 18 


1479 


1480 


shell variables (bash) 


nolinks, 18 

notify, 17 

OLDPWD, 15 

OPTARG, 16 

OPTERR, 17 

OPTIND, 16 

OSTYPE, 16 

PATH, 16 

PPID, 15 

PROMPT_COMMAND, 

Li 

PS1, 16 

PS2, 16 

PS3, 17 

PS4,17 

PWD,15 

RANDOM, 15 

REPLY, 15 

SECONDS, 15 

SHLVL, 15 

TMOUT,17 

UID, 15 

shells 

archives, creating, 484-487 

Bourne-again, 11-46 
aliases, 23-24 
arguments, 11 
arithmetic evaluation, 34 
blanks, 12 
bugs 46 
command execution, 25 
comments, 14 
compound commands, 13 
control operators 12 
environments, 25-26 
exape character, 14 
exit status 26 
expansion, 18-21 
files, 46 
functions 23 
history list, 32-33 
invocation, 45-46 
job control, 24-25 
ligs 12-13 
meta characters 12 
name, 12 
options 11 


parameters, 14-15 
pipdines(|), 12 
prompting, 26 
quoting, 14 

readline, 27-32 
redirection, 21-23 
reserved words, 12 
hal variables 15-18 
ggnals 25 

gmple commands 12 
words 12 


built-in commands, 35-45 


alias 35 

bg, 35 

bind, 35 
break, 35 
builtin, 35 
cd, 35-36 
command, 36 
continue, 36 
declare, 36 
dirs, 36 
echo, 36-37 
@abling/disabling, 37 
eval, 37 
exec, 37 
exit, 37 
export, 37 
fc, 37-38 

fg, 38 
getopts 38 
hash, 38 
hap, 38 
history, 39 
jobs 39 
kill, 39 

let, 39 

local, 39 
logout, 39 
popd, 39-40 
pushd, 40 
pwd, 40 
read, 40 
readonly, 40 
return, 40 
gt, 40-42 
shift, 42 


supend, 42-43 
tet expr, 43 
time, 43 
trap, 43-44 
type, 44 
ulimit, 44-45 
umask, 45 
unalias, 45 
unsd, 45 
wait, 45 
commands, executing, 1047 
exiting, 37 
interactive, 45 
login, 45 
changing, 63 
exiting, 39 
pathname, 1186 
remote, 466-467 
grve, 1385-1386 
suspending execution, 42-43 
user, getting, 946-947 
shells file, 1186 
shift (shell command), 42 
shlock, 487 
SH LVL variable (bash), 15 
shmctl, 849-851 
commands, 850 
errors, 851 
system calls, 851 
shmget, 851-853 
bugs, 853 
errors, 852 
system calls, 852 
shmop, 853-854 
show-all-if-ambiguous 
variable (readline), 28 
showmount, 1396 
showrgb, 488 
shrinkfile, 488 
shutdown, 855, 1396-1397 
bugs, 1397 
errors, 855 
files, 1397 
options, 1397 
sigaction, 855-857 
sigaddset, 1019-1020 
sigblock, 858 


sigdelset, 1019-1020 
sigemptyset, 1019-1020 
sigfillset, 1019-1020 
siggetmask, 858 
siginterrupt( ) function, 1019 
sigismember, 1019-1020 
sigmask, 858 
signal, 857-858, 1248-1249 
bugs, 1249 
signal messages, printing, 
996 
signals 
available (list of), 1248-1249 
bash, 25 
blocked 
changing list of, 856 
rdeagng, 858-859 
changing process action, 
855-856 
describing with strings, 1038 
handling, 857-858 
interrupting system calls, 
1019 
masks 
manipulating, 858 
replacing, 856 
pending, examining, 856 
POSIX signal set operations, 
1019-1020 
sending to processes, raise 
function, 1000 
waiting for, 817 
signatures, tin, 528 
sigpause, 858-859 
sigpending, 855-857 
sigprocmask, 855-857 
sigreturn, 859 
sigsetmask, 858 
sigsuspend, 855-857 
sigvec, 860 
simple commands (bash), 12 
simpleinit, 1397-1399 
bugs, 1399 
files, 1398 
sin( ) function, 1020-1021 
sinh( ) function, 1021 
sirtopnm, 488-489 


site (ftp command), 152 
size, 489-490 
copying, 489-490 
ftp command, 152 
options, 489 
slattach, 1399 
sic command (telnet), 510 
sldtoppm, 490-491 
sleep( ) function, 1021 
sliplogin, 1399-1401 
diagnostics, 1400 
/etc/slip.hosts format, 1400 
example, 1400 
parameters, 1400 
smb filesystem, 1126 
smproxy, 491-492 
snprintf function, 992-996 
SOCK_DGRAM sockets, 
860-861 
SOCK_RAW sockets, 861 
SOCK_RDM sockets, 861 
SOCK_SEQPACKET sockets, 
860-861 
SOCK_STREAM sockets, 
860-861 
socket, 860-861 
erors, 861 
socket types, 860 
SOCK_DGRAM, 
860-861 
SOCK_RAW, 861 
SOCK_RDM, 861 
SOCK_SEQPACKET, 
860-861 
SOCK_STREAM, 
860-861 
socketcall, 862 
socketpair, 862-863 
sockets 
connections 
accepting, 740-741 
initiating, 752-753 
listening for, 792-793 
creating, 860-861 
names 
binding, 745-746 
getting, 769 


source command (xauth) 


options, 770-771 
getting/setting, 769-772 
SO_BROADCAST, 771 
SO_DEBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO_KEEPALIVE, 770 
SO_LINGER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIMEO, 771 
SO_REUSEAD DR, 770 
SO_SNDBUF, 771 
SO_SNDLOWAT, 771 
SO_SNDTIMEO, 771 
SO_TYPE, 771 

pairs, creating, 862-863 

peers, getting names, 765 

receiving messages from, 

826-828 
sending messages from, 
842-843 

system calls, 862 

types, 860 
SOCK_DGRAM, 

860-861 
SOCK_RAW, 861 
SOCK_RDM, 861 
SOCK_SEQPACKET, 

860-861 
SOCK_STREAM, 

860-861 

soft-reset( ) action (xterm), 
715 

Solitaire files, converting to 
portable anymaps, 488-489 

sort, 492-493 

sorted arrays, searching, 
900-901 

sorted files, removing 
duplicate lines, 560 

sorted word lists, compress- 
ing/uncompressing, 496 

sorting arrays, 1000 

sound drivers, boot-time 
parameters, 1224 

source command (xauth), 591 
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spaces, converting to tabs, 559 
spctoppm, 494 
special parameters, bash, 
14-15 
! (exclamation points), 15 
#(pound signs), 15 
$ (dollar signs), 15 
* (asterisks), 15 
- (hyphens), 15 
? (question marks), 15 
@ (at signs), 15 
_ (underscores), 15 
0,15 
spell-checking, 274, 280 
buildhash, 279 
findaffix, 280 
icombine, 281 
ijoin, 281 
ispall, 274-279 
ispall dictionaries, 
1084-1090 
affix file 1084-1085 
alternate string characters, 
1087 
character-set section, 1086 
flags 1088 
headers 1085 
options tatements, 
1085-1086 
prefix/suffix tables, 1088 
root words, 1084-1085 
munchlist, 279-280 
tryaffix, 281 
split, 494-495 
splitting files, 85-86, 119-120 
spool queue 
examining, 298-299 
removing jobs from, 
301-302 
SPOT satellite images, 
converting to portable 
graymaps, 495 
spottopgm, 495 
sprintf function, 992-996 
sprintf( ) function, awk, 
167-168 
sputoppm, 495-496 


sq, 496 
sqrt( ) function, 1023 
square roots (returning), 1023 
srand( ) function, 1001 
srand48( ) functions, 912 
srandom( ) function, 
1001-1002 
sscanf function, 1013-1015 
st, 1096-1100 
ioctl( ) calls, 1097-1100 
return values, 1100 
stack, saving context, 1018 
standard colormap utility (X), 
699-700 
standard error output, 
redirecting, 22 
standard output, redirecting, 
22 
start-cursor-extend( ) action 
(xterm), 714 
start-extend( ) action (xterm), 
714 
startup time 
adjusting to GMT, 1424- 
1425 
converting, 1430 
startx, 496-497 
stat, 863-864 
statements, awk, 167-168 
states (system), updating, 
1414-1415 
statfs, 865-866 
status 
cvs, 102 
ftp, 152 
telnet command, 512 
stdarg, 1023-1024 
stdio library, 1025-1027 
bugs, 1026 
functions, 1026-1027 
stime, 866 
stpcpy( ) function, 1027-1028 
streasecmp( ), 1028 
strcat( ) function, 1028-1029 
strchr( ) function, 1029 
strcmp( ) function, 1029-1030 
strcoll( ) function, 1030 
strcpy( ) function, 1030-1031 


strcspn( ) function, 
1038-1039 
strdup( ) function, 1031 
stream-oriented editor, see sed 
streams 
binary, input/output 
(getting), 926-927 
block buffered, 1016 
buffering operations, 
1016-1017 
checking/resetting status, 
919-920 
closing, 919 
directory 
current location (ré&urn- 
ing), 1048 
resetting, 1011 
flushing, 920-921 
line buffered, 1016 
opening, 924-925 
repositioning, 927-928 
unbuffered, 1016 
strerror( ) function, 1032 
strfry( ), 1032 
strftime( ) function, 
1032-1034 
conversion specifiers, 1033 
tm structure members, 1034 
string constants, awk, 
169-170 
string functions, awk, 169 
string variables, configura- 
tion-dependent, 906-907 
string( ) action (xterm), 714 
strings, 498 
byte 
copying, 900 
operations 901 
writing zeros to, 902 
comparing, 1029-1030 
byte, 899-900 
ignoring case, 1028 
using current locale 1030 
concatenating, 1028-1029 
converting 
to doubles 898, 
1039-1040 
to integers 898-899 


to long integers 899, 
1041 
to multibyte character 
(from wide character), 
1061 
to tm structure 
1036-1037 
to uns gned long integers, 
1041-1042 
to wide character (from 
multibyte), 977-978 
copying, 498, 1030-1031 
gpcpy( ) function, 
1027-1028 
describing signals with, 1038 
duplicating, 1031 
extracting tokens from, 
1037-1040 
length (calculating), 1035 
locating characters in, 953, 
1029 
options, 498 
outputting, 997-999 
randomizing, 1032 
searching, for character sets, 
1035-1039 
string operation functions, 
1034-1035 
transformation, 1042-1043 
ge als substrings 
strip, 499 
strlen( ) function, 1035 
strncasecmp( ), 1028 
strncat( ) function, 1028-1029 
strncmp( ) function, 
1029-1030 
strncpy( ) function, 
1030-1031 
strpbrk( ) function, 
1035-1036 
strptime( ) function, 
1036-1037 
bugs, 1037 
fidd descriptors, 1036-1037 
strrchr( ) function, 1029 
strsep( ) function, 1037-1038 
strsignal( ) function, 1038 
strspn( ) function, 1038-1039 


strstr( ) function, 1039 
strtod( ) function, 1039-1040 
strtok( ) function, 1040 
strtol( ) function, 1041 
strtoul( ) function, 1041-1042 
struct (ftp command), 152 
strxfrm( ) function, 
1042-1043 
subdirectories, MS-DOS 
creating, 326 
moving, 327 
removing, 329 
renaming, 329-330 
subroutines 
endnetent, 936-937 
getnetbyaddr, 936-937 
getnetbyname, 936-937 
getnetent, 936-937 
subst, 500-501 
substrings 
locating, 1039 
locating in memory areas, 
981 
ge also strings 
suffixes, 1249-1252 
sum, 501 
Sun icons, converting to 
portable bitmaps, 262 
Sun raster files, converting to 
portable anymaps, 438 
SuperProbe, 501-503 
bugs, 503 
options, 502 
running, 502-503 
suspend (shell command), 
42-43 
suspending execution, 1061 
swab( ) function, 1043 
swap area, setting up, 
1327-1328 
swap device parameter, values, 
1374 
swapoff, 866-867, 1401 
errors, 867 
files, 1401 
priority, 867 
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swapon, 866-867, 1401 
errors, 867 
files, 1401 
priority, 867 
swapping 
eabling/disabling, 1401 
starting/ stopping, 866-867 
priority, 867 
swapping bytes, 1043 
symbolic links, 867-869 
reading values, 823-824 
symlink, 867-869 
sync, 869, 1401-1402 
synchronizing files with 
memory maps, 811 
synchronous!/O, 
multiplexing, 835-837 
syscall macros, 738 
syscall( ) macros, 738 
sysconf( ) function, 
1043-1045 
sysctl, 869-871 
sysfs, 871 
sysinfo, 871-872 
sysklogd, 1402-1404 
configuration file, 1402- 
1403 
FIFOs, 1403 
files, 1404 
installing, 1403 
remote logging, 1403 
security, 1403-1404 
syslog, 872-874 
syslog( ) function, 1045-1046 
syslog.conf, 1186-1188 
action field, 1186-1187 
examples, 1187-1188 
facility keyword, 1187 
level keyword, 1187 
selector field, 1186-1187 
syslogd, 1404-1405 
configuration file, 1186- 
1188 
action fidd, 1186-1187 
examples 1187-1188 
facility keyword, 1187 
level keyword, 1187 
Sector fidd, 1186-1187 
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files, 1405 
options, 1405 
system 
configuration, getting 
information at runtime, 
1043-1045 
displaying information 
about, 562 
load average, graphing, 533 
page size, getting, 765 
parameters, reading/writing, 
869-871 
printing activity summary, 
573 
shutting down, 1396-1397 
state, updating, 1414-1415 
status server, 1386-1387 
message format, 
1386-1387 
system (ftp command), 152 
system calls, 738-739 
calling directly, 738 
interrupting with signals, 
1019 
IPC, 789 
obsolete, 814 
prototypes, 738 
socket, 862 
syscall macros, 738 
undocumented, 881 
unimplemented, 881-882 
system logging, 1402-1404 
configuration file, 
1402-1403 
FIFOs, 1403 
making log entries, 295-296 
messages, 1404-1405 
remote, 1403 
sending messages to, 
1045-1046 
System V interprocess 
communication, 1144-1146 
message queues, 1145 
resource access permissions, 
1144-1145 
semaphore sets, 1145-1146 
shared memory segments, 
1146 


System V IPC keys, convert- 
ing pathnames/project 
identifiers to, 929-930 

system( ) function, 1047 

sysv filesystem, 1125 


T 


Tab Window M anager, see 
twm 
tables 
descriptor, size (getting), 
760-761 
file 
adding entries, 
1428-1429 
dexription, 1425-1426 
initializing, 1427 
moving files to end, 1431 
removing files 1431-1432 
gructure 1426 
table entries, 1426 
unreerenced entries 
(fetching), 1428 
hash 
creating, 951 
freeing memory, 951 
gar ching, 951 
IP routing (manipulating), 
1379-1380 
local descriptor, reading/ 
writing, 800 
RARP, manipulating, 1373 
troff, formatting, 236-237 
tabs, converting to spaces, 137 
tac, 503-504 
tag (cvs command), 102-103 
tag files 
emacs, 135-137 
generating, 87-88 
vi, 135-137 
tail, 504 
talk, 505 
talkd, 1405-1406 
tan( ) function, 1047-1048 
tanh( ) function, 1048 
tcal, 506 


tcdrain( ), 876, 1052 
tcflow( ), 876, 1052 
tcflush( ), 876, 1052 
tcgetattr( ), 876, 1051 
tcgetpgrp( ), 877, 1053 
tcsendbreak( ), 876, 1052 
tcsetattr( ), 876, 1052 
tcsetpgrp( ), 877, 1053 
tdelete, 1056-1058 
tek-copy( ) action (xterm), 
716 


tek-page( ) action (xterm), 
715 
tek-reset( ) action (xterm), 
716 
telinit, 1307-1309 
diagnostics, 1309 
files, 1308 
run levels, 1308 
telldir( ) function, 1048 
telnet, 507-512 
commands, 508-512 
512 
2,512 
close 508 
disolay argument, 508 
environ, 511 
mode, 508 
ope hos, 508 
quit, 508 
snd arguments, 508-509 
st, 509-510 
dc, 510 
gatus, 512 
toggle, 511-512 
uns&, 509-510 
z,512 
environment, 512 
files, 512 
options, 507 
Tdnet protocol 
DARPA server, 1406-1407 
interface, see telnet 
telnetd, 1406-1407 
tempnam( ) function, 1049 
temporary filenames, creating, 
983-984 


temporary files 
creating, 983, 1053-1054 
naming, 1049, 1054 
tenex (ftp command), 152 
termcap, 1188-1197 
Boolean capabilities, 1189 
numeric capabilities, 
1189-1190 
string capabilities, 
1190-1197 
control codes, 1195-1196 
terminals 
attributes, 1049-1053 
getting, 876 
sting, 482-483, 876 
baud rate, 1049-1053 
capability database, 
1188-1197 
Boolean capabilities 1189 
numeric capabilities 
1189-1190 
gring capabilities, 
1190-1197 
controlling terminal, 
1100-1101 
creating typescript of 
sessions, 474-475 
displaying last login, 
285-286 
foreground processes, group 
ID, 1049-1053 
initializing, 539-542 
line control, 1049-1053 
name and device list, 1197 
names (returning), 1058 
resetting, 456 
sevial lines, 1101 
termios functions, 874-878 
type mapping, 540-541 
type setting in shell 
environment, 540 
virtual hangups, 885 
window size, setting, 
456-457 
terminating processes, 
283-284 


terminating programs 
abort( ) function, 892 
assert( ) function, 895-896 
termios functions, 874 
flag constants, 874-876 
termios structure 
c_cflag flag constants, 1051 
c_iflag flag constants, 1050 
c_Iflag flag constants, 1051 
c_oflag flag constants, 
1050-1051 
test expr (shell command), 43 
text 
compressed, viewing, 
733-734 
filters, more, 327-328 
formatting line lengths, 143 
rendering to bitmaps, 
355-356 
sorting, 492-493 
editors, Avis, 126-128 
files 
converting for printing, 
429-430 
creating gcal resource files 
from, 558 
tfind, 1056-1058 
tfmtodit, 513 
TFTP (Trivial File Transfer 
Protocol), 1407 
DARPA server, 1407 
tftp, 514-515 
TFTP (Trivial File Transfer 
Protocol), 514 
tftpd, 1407 
tgatoppm, 515 
TI_ACTIVEFILE environ- 
ment variable, 529 
TILNOVROOTDIR environ- 
ment variable, 529 
TIFF files, converting to 
portable anymaps, 515-516 
tifftopnm, 515-516 
tilde expansion (bash), 19 
time 
calculating differences, 911 
getting/setting, 772-773 
in seconds 878 


tin 


returning current, 928-929 
setting, 866 
startup 
adjusingtoGMT, 
1424-1425 
converting, 1430 
time functions, 878 
awk, 169 
time server daemon, 
1407-1408 
time zones 
compiling, 1419-1422 
printing, 1419 
time-sharing scheduling, 834 
timed, 1407-1409 
control program, 1408-1409 
files, 1408 
timedc, 1408-1409 
timers (event), managing, 
1424 
times 
binary, converting to ASCII, 
909-911 
converting 
to ASCII, 984-986 
initializing convergon 
information, 986-988, 
1058-1060 
grings to numbers, 
989-990 
to tm ¢ructure, 
1036-1037 
formatting, strftime{ ) 
function, 1032-1034 
process, getting, 878-879 
time zone information files, 
1197-1198 
user/systen, printing, 43 
times (shell command), 43 
times function, 878-879 
timestamps, changing, 536 
tin, 516-533 
articles 
automatic mailing, 528 
autosdect/autokilll, 
526-527 
crosposting, 527 


tin 


customizing quote string, 
527 
mailing, 527 
piping, 527 
posting, 527 
printing, 527 
saving, 527-528 
tagging/untagging, 528 
bugs, 531 
commands 
article viewer, 522-524 
editing, 519 
global options menu, 524- 
525 
group index, 521-522 
newsgroup selection, 
519-520 
spool directory sdection, 
520 
thread listing, 522 
environment variables, 
528-530 
ADD_ADDRESS, 529 
AUTOSUBSCRIBE, 529 
AUTOUNSUBSCRIBE, 
530 
BUG_ADDRESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
NNTPSERVER, 529 
ORGANIZATION, 529 
REPLYTO, 529 
TI_ACTIVEFILE, 529 
TI_LNOVROOTDIR, 529 
TIN_HOMEDIR, 528 
TIN_INDEXDIR, 529 
TIN_LIBDIR, 529 
TIN_SPOOLDIR, 529 
TINRC, 528 
VISUAL, 529 
files, 531 
group attributes, 526 
index files, 517-518 
moving between levels, 519 
news administration, 518 
options, 516-517 
screen format, 518-519 


signatures, 528 
starting, 518 
tinrc configurable variables, 
525-526 
xterm buttons, 530-531 
TIN_HOMEDIR 
environment variable, 528 
TIN_INDEXDIR 
environment variable, 529 
TIN_LIBDIR environment 
variable, 529 
TIN_SPOOLDIR 
environment variable, 529 
tinrc configurable variables, 
525-526 
ge alm tin 
TINRC environment variable, 
528 
tload, 533 
TMOUT variable (bash), 17 
/tmp directory, 1237 
tmpfile{ ) function, 
1053-1054 
tmpnam( ) function, 1054 
toascii( ) function, 1055 
toggle command (telnet), 
511-512 
tokens, extracting from 
strings, 1037-1040 
tolower( ) function, 
1055-1056 
top, 533-535 
bugs, 535 
commands, 534-535 
fidd descriptions, 534 
options, 534 
topological sorting (graphs), 
542 
touch, 536 
toupper( ) function, 
1055-1056 
tr, 536-539 
character classes, 537-538 
escape characters, 537 
ranges, 537 
repeated characters, 537 
specifying character sets, 537 


squeezing/deleting, 538-539 
translating, 538 
warning messages, 539 
tr2tex, 1252-1253 
trace (ftp command), 152 
traceroute, 1409-1412 
examples, 1411 
options, 1410 
transforming strings, 
1042-1043 
translating/deeting charac- 
ters, 536-539 
trap (shell command), 43-44 
Trivial File Transfer Protocol, 
see TFTP 
troff 
compiling pictures for, 
211-215 
converting to LaT eX, 
1252-1253 
formatting tables, 236-237 
output format, 1129-1131 
TrueVision T arga files, 
converting to portable 
pixmaps, 515 
truncate, 879-880 
tryaffix, 274, 281 
files, 281 
ge alm ispal 
tsearch, 1056-1058 
tset, 539-542 
compatibility, 542 
environment, 541 
files, 541 
options, 540 
setting environment, 540 
terminal type mapping, 
540-541 
tsort, 542 
tty, 1100-1101 
ttyname, 1058 
ttys, 1101 
ttytype, 1197 
tune2fs, 1412-1413 
tunedp, 1413-1414 
twalk, 1056-1058 


twm, 542-557 

bindings, 552-553 

bugs, 557 

customizing, 543-544 

environment, 557 

files, 557 

functions, 554-556 
554 
f.autoraise, 554 
f.backi conmgr, 554 
f.beep, 554 
f.bottomzoom, 554 
f.drcledown, 554 
f.drcleup, 554 
f.colormap, 554 
f.deiconify, 554 
f.ddete, 554 
f.daltastop, 554 
f.destroy, 554 
f.downiconmgr, 554 
fexec, 554 
f.focus 554 
f.forcenove 555 
f.forwiconmgr, 555 
f.fullzoom, 555 
f.function, 555 
f.hbzoom, 555 
f.hidaiconmgr, 555 
f.horizoom, 555 
f.htzoom, 555 
f.hzoom, 555 
f.iconify, 555 
f.identify, 555 
f.lefticonmgr, 555 
f.leftzoom, 555 
flower, 555 
fmenu, 555 
f.move, 555 
f.nexticonmgr, 555 
f.nop, 555 
f.previconmgr, 555 
f.priority, 555 
f.quit, 555 
fraise 555 
f.raisdower, 555 
f.refresh, 555 
firedze 555 


fretart, 555 
f.righticonmgr, 555 
f.rightzoom, 556 
f.saveyoursaf, 556 
f.hhowiconmgr, 556 
f.sorticonmgr, 556 
ftitle, 556 
f.topzoom, 556 
f.unfocus, 556 
f.upiconmgr, 556 
f.vlzoom, 556 
f.vrzoom, 556 
f.warpring, 556 
f.warpto, 556 
f.warptoi conmgr, 556 
f.warptoscreen, 556 
f.winrefresh, 556 
f.zoom, 556 


twm 


Forcelcons 547 
FrameP adding, 547 
Grayscale, 547 
IconBackground, 547 
IconBordeC olor, 547 
IconBorderW idth, 547 
IconD irectory, 547 
IconF ont, 547 
|conF oreground, 547 
|conifyB yU nmapping, 
547 
IconM anagerBackground, 
547 
IconM anagerD ontShow, 
547 
IconM anager ont, 548 
IconM anagerF oreground, 
548 


icons, 557 
menus, 556-557 
options, 543 
starting, 543 
startup files, 543-544 
variables, 544-552 
AutoRaise 544 
AutoRdativeReize 
544-545 
BordeColor, 545 
BordaT ileB ackground, 
545 
BorderT ileF oreground, 
545 
BordeW idth, 545 
Button|ndent, 545 
ClientBorderW idth, 545 
Color, 545-546 
ConstrainedM oveT ime 
546 


Icon 
54 
Icon 


548 


Icon 
Icon 
Icon 
Icon 


M anagerG eometry, 
8 
M anageH ighlight, 


Managers, 548 

M anageShow, 548 
Region, 548 

5 548-549 





InterpolateM enuC olors 


54 


9 


M akeT itle 549 
M axW indowSize 549 


Man 
Man 
Man 
Man 
Man 

54 
Man 

54 


uBackground, 549 
uF ont, 549 

uF oreground, 549 
uShadowC olor, 549 
uT itleB ackground, 
9 

uT itleF oreground, 

9 


Cursors, 546 

D ecoratel ransients, 546 

D daultBackground, 546 

D edaultF oreground, 547 

D daultF unction, 552 

D ont! conifyB yU nmapping, 
547 

D ontM oveO ff, 547 

D ontSquezeT itle 547 


M onochrome, 549 

M oveD dta, 549 

N oBackingStore 549 
NoCasSenstive, 549 
N oD daults 549 

N oGrabServer, 549 

N oH ighlight, 550 

N olconM anagers 550 
N oM euShadows 550 
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N oRaisO nD dconify, 550 
N oRaiss0 nM ove 550 
N oRaiseO nRedze 550 
N oRaiseO nW arp, 550 
N oSaveU nders 550 
N oStackM ode, 550 
NoTitle 550 
N oT itl ocus, 550 
N oT itleH ighlight, 550 
OpaqueM ove, 550 
Pixmaps, 550 
Priority, 550 
RandomPlacement, 550 
Resize ont, 551 
RestartPreviousState 551 
SaveC olor, 551 
Showl conM anager, 551 
Sortl conM anager, 551 
Squeezel itle 551 
Startl conified, 551 
TitleBackground, 551 
TitleB uttonBorderW idth, 
551 
TitleFont, 552 
TitleF oreground, 552 
Title adding, 552 
Unknownlcon, 552 
UseP Postion, 552 
WarpCursor, 552 
W arpU nmapped, 552 
WindowF unction, 552 
WindowRing, 552 
XorValue 552 
Zoom, 552 
windows, 543 
creating, 543 
reizing, 543 
txt2gcal, 558 
type 
ftp command, 152 
shell command, 44 
TZ environment variable, 987 
tzfile, 1197-1198 
tzset, 986-988 
files, 988 
TZ environment variable, 
987 
tzset( ) function, 1058-1060 








U 


UID variable (bash), 15 
ul, 558-559 
ulimit (shell command), 
44-45 
umask, 880 
ftp command, 152 
shell command, 45 
umsdos filesystem, 1125 
unalias (shell command), 45 
uname, 880-881 
unbuffered streams, 1016 
underlining, 558-559 
underscores (_), bash special 
parameters, 15 
undocumented system calls, 
881 
unexpand, 559 
ungetc( ) function, 945 
Unicode, 1065, 1253-1255 
ASCIl-compatible encoding, 
1255-1256 
combining characters, 1254 
implenentation levels, 1254 
Web site, 1065 
unimplemented system calls, 
881-882 
uniq, 560 
Universal Product C ode 
bitmaps, creating, 368 
UNIX 
copying M S-D OS files to/ 
from, 317-318 
filenames, restoring, 
324-325 
files, copying 
bawem sytens 563-565 
toM S-DOS, 335 
unlink, 882 
unlocking memory 
munlock, 811-812 
munlockall, 812-813 
unmapping files to memory, 
799-800 


unmount, 802-804, 
1328-1332 
bugs, 1332 
errors, 803 
files, 1332 
options, 1331 
return value, 803 
unset 
shell command, 45 
telnet command, 509-510 
unshar, 560-561 
unsq, 496 
update (cvs command), 
103-104 
update state, 1414-1415 
updatedb, 561-562 
uppercase, converting letters 
to, 1055-1056 
uptime, 562 
uselib, 883 
Usenet 
administration, 1344-1346 
archiver, 1262-1263 
articles 
expiring, 1121-1123 
libinn routines 962-966 
purging, 1292-1293 
record of, 1131-1132 
retrieving froNNTP 
srve, 340-341 
ganding to remote NNTP 
grve, 1312-1313 
gnding to remote ste 
1349-1350 
specifying distribution, 
1158-1163 
batch files, converting to 
INN, 1281-1282 
control messages, handling, 
1115-1116 
databases, recovering, 
1342-1344 
history file 
displaying filenames from, 
226-227 
removing filevames, 
1370-1371 


innwatch supervision, 
1142-1144 
log files, 1163-1165 
lis of, 1164 
maintenance 1346-1347 
messag@action fidds, 
1163-1164 
moderated newsgroups, mail 
addresses, 1151-1152 
newsgroups, listing active, 
1104-1105 
sending articles to servers, 
267-269 
U senix FaceSaver files, 
converting to portable 
graymaps, 147 
user (ftp command), 152 
user group file, 1131 
user ID s (processes), setting, 
848-849 
real and effective, 847-848 
userlist, 563 
usernames 
getting, 934-935 
remote lookup, 1134-1135 
users 
adding to system, 
1258-1259 
displaying last login, 
285-286 
file permissions, checking, 
741-742 
IDs, getting, 773 
listing, 563 
logins, preventing, 1168 
outputting logged in 
on local machines 474 
on naworks, 472-473 
preference utility (X), 
690-693 
printing activity summary 
(w), 573 
quotas, editing, 1291-1292 
sending messages to, 473, 
576-577 
shells, getting, 946-947 
switching between, 296 


talking to online 505 
writing messages to, 574, 
1383 
usleep( ) function, 1061 
/usr directory, 1237 
/usr/X11R6 directory, 1237 
/usr/X11R6/bin directory, 
1237 
/usr/X11R6/lib directory, 
1237 
/usr/X11R6/lib/X11 directory, 
1237 
/usrX11R6/include/X11 
directory, 1237 
ustat, 883-884 
UTF-8, 1255-1256 
examples, 1256 
properties, 1255-1256 
utime, 884-885 
utimes, 884-885 
utmp, 1198-1200 
utmp file entries, accessing, 
947-948 
utmp/wtmp entries, manag- 
ing, 480-481 
utmpname{ ) function, 947 
uucico, 1415-1417 
files, 1416-1417 
options, 1415-1416 
uucp, 563-565 
bugs, 565 
execution daemon, 572 
files, 564-565 
options, 564 
remote command execution, 
569-571 
status inquiry, 566-569 
UUCP 
connections, receiving news, 
463-464 
file transfer requests, 
processing, 1415-1417 
uudecode, 565-566 
uuencode, 565-566, 1200 
uustat, 566-569 
examples, 568-569 
files, 569 
options, 567-568 


variables 


uux, 569-571 
bugs, 571 
examples, 571 
files, 571 
options, 570-571 
restrictions, 571 
uuxqt, 572 


V 


variable argument lists 
(declaring), 1023-1024 
variables 
awk, 163-165 
arrays, 164 
built-in, 163-164 
typing and conversion, 
164-165 
bash, 15-18 
allow-null_ glob 
_expangon, 17 
auto_reume, 18 
BASH, 15 
BASH_VERSION, 15 
cdable vars, 18 
CDPATH, 16 
command_oriented_hisory, 
17 
ENV, 16 
EVID, 15 
FCEDIT, 17 
FIGNORE, 17 
glob_dot_filevames 17 
hitchars 17-18 
HISTCMD, 16 
HISTFILE, 17 
HISTFILESIZE, 17 
HISTSIZE, 17 
HOME, 16 
hostname_compleion_file 
18 
HOSTTYPE, 16 
IFS, 16 
IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 


1489 


variables 


MAIL_WARNING, 16 

MAILCHECK, 16 

MAILPATH, 16 

no_exit_on_failed_exer, 
18 

noclobber, 18 

nolinks 18 

notify, 17 

OLDPWD, 15 

OPTARG, 16 

OPTERR, 17 

OPTIND, 16 

OSTYPE, 16 

PATH, 16 

PPID, 15-17 

PROMPT_COMMAND, 
17 


comment-begin, 28 
completion-query-itens, 
28 
convet-mea, 28 
editing-mode 28 
expand-tilde, 28 
horizontal-scroll-mode 28 
keymap, 28 
mark-modified-lines, 28 
meta-flag, 28 
output-meta, 28 
ow-all-if-ambiguous 28 
string, configuration- 
dependent, 906-907 


ves, 1101-1102 

vcsa, 1101-1102 

vectors, reading/writing, 
824-825 

verbose (ftp command), 152 

vfat filesystem, 1125 

case sensitivity (mtools and), 
332 

vfork, 758 

vfprintf function, 992-996 

viscanf function, 1013-1015 

vhangup, 885 

vi, see elvis 

video hardware, identifying, 
501-503 

video mode tuner (X Freeg6), 
719-720 


reports, 1417-1418 
VISUAL environment 
variable, 529 
visual-bell( ) action (xterm), 
716 
vm86, 885-886 
vmstat, 1417-1418 
volume labels (MS-DOS), 
creating, 325-326 
vprintf function, 992-996 
vscanf function, 1013-1015 
vsnprintf function, 992-996 
vsprintf function, 992-996 
vsscanf function, 1013-1015 


W 


w, 573 
wait, 886-888 
errors, 887 
shell command, 45 
status macros, 887 
wait3, 888-889 
wait4, 888-889 
waitpid, 886-888 
wall, 574 
wc, 574 
wcstomb( ) function, 
1061-1062 
wcstombs( ) function, 1061 
Web sites, U nicode, 1065 
whereis, 575-576 


PS1, 16 buttons, 719 while (bash command), 13 
PS2, 16 moving display, 719 wide character strings, 
PS3,17 options, 720 converting to multibyte 
PS4, 17 vidr, 303-304 character strings, 1061 
PWD,15 view, see elvis wide characters, converting to 
RANDOM, 15 vipw, 1418-1419 multibyte characters, 
REPLY, 15 virtual 8086 mode, entering, 1061-1062 
SECONDS, 15 885-886 widgets 
SHLVL, 15 virtual consoles, 1066 bitmap application, 54-57 
TMOUT, 17 memory, 1101-1102 editres, 125-126 
UID, 15 virtual framebuffer X server, xclipboard, 596 

declaring, 36 717-718 xclock, 595 

local, creating, 39 virtual memory xconsole, 598 

readline, 28 addresses, remapping, xcutsel, 599 
bdl-syle, 28 805-806 xdm authentication widget, 


609-610 
actions supported, 610 
resources 609-610 
xfd, 634-635 
xlogo, 668 
xmag, 671 
windows, X 
dumping utility, 721-722 
information utility, 722-724 
word splitting (bash), 21 
words 
bash, 12 
finding first bit set, 921 
input/output, 948 


wrapping input lines, 143-144 

write, 576-577, 889-890 
errors, 889-890 

writev, 824-825, 1003-1004 
bugs, 1004 
errors, 825, 1004 

wtmp, 1198-1200 


X 


X Color M anagement System, 
D evice Color C haracteriza- 
tion utility, 592-593 

X commands, grops, 232-233 

X font servers 

displaying information 
about, 145 

generating BD F fonts, 
146-147 

listing fonts, 145-146 

X sessions, initializing, 
496-497 

X Window System 

clients 
clipboard diet, 595-597 
listing applications 
669-670 
clock, 593-595 
Display M anager, 599-614 
authentication widget, 
609-610 
choose, 607 
configuration file 606 
controlling, 613 
environment variables 
608 
files, 613 
limitations 613 
local server specification, 
607-608 
options 600-601 
reset program, 612 
resources, 601-606 
reourcesfile 608 
grver control, 612-613 
gssion program, 611-612 
gesions, 600 


X11 bitmaps, converting to portable 


stup program, 608-609 
gartup program, 610-611 
XD MCP service access 
control, 606-607 
emacs, 131-132 
fonts 
displaying all characters 
in, 633-636 
listing, 670-671 
image displayer, 725-726 
environment, 726 
options, 725-726 
imake, 266 
initializer, 664-666 
keymaps, modifying, 
672-676 
LBX proxy server, 286-287 
logo, 667-668 
magnifying screen, 671-672 
monitoring systen console 
messages, 597-598 
property displayer, 677-681 
constructing formats, 679 
examples, 680 
format characters 679 
S#ecting windows, 678 
remote program starts, 676 
resource database utility, 
681-684 
filesymbols 681-682 
options, 682-684 
root window parameters 
(setting), 693-694 
screen, refreshing, 684-685 
server information utility, 
614 
servers 
access control program, 
643-645 
display saver, 685-690 
font server, 641-643 
killing dients 666-667 
virtual framebuffer, 
717-718 
XFree86, 636-641 
Session M anager, 694-698 
default startup applica- 


tions 695 
options, 695-698 
proxy, 698 
remote applications 698 
Sesion menu, 695-696 
SM_SAVE_DIR 
environment variable 
695 
garting sssons 695 
tester, 698-699 
xeon file 695 
standard colormap utility, 
699-700 
T ab Window M anage,, 
542-557 
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options, 543 
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gartup files 543-544 
variables, 544-552 
windows, 543 
terminal emulator, 700-717 
actions 713-716 
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environment, 717 
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options, 701-705 
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resources 705-710 
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options, 578-585 
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commands, 588, 591 
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renove, 591 
source 591 
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environment, 589 
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environment, 597 
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options, 596 
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widgets, 596 
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options, 594 
widgets, 595 
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xconsole, 597-598 
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609-610 
actions supported, 610 
resources 609-610 
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files, 613 
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local server specification, 
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options, 600-601 
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resources, 601-606 
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isolayM anage.D ISPLAY. 
cpp, 603 

splayM anager.D ISPLAY. 
failsafeClient, 605 
isolayM anager.D ISPLAY. 
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splayM anager.D ISPLAY. 
grabT imeout, 605 
splayM anager.D ISPLAY. 
opaD day, 604 
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reset, 604 
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splayM anager.D ISPLAY. 
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resources, 603 

splayM anager.D ISPLAY. 
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603 
DigplayM anager.keyF ile 
602 
isolayM anager.lockPidF ile 
602 
isplayM anager.pidFile 
602 
isolayM anager.randomF ile 
603 
isplayM anager.remove 
Domainname, 602 
isplayM anager.requedP ort, 
601 
isplayM anager.servers, 
601 
resources file, 608 
server control, 612-613 
session program, 611-612 
sessions, 600 
setup program, 608-609 
startup program, 610-611 
XDM CP service access 
control, 606-607 
XD MCP service, access 
control, 606-607 
xdpyinfo, 614 
XF86_8514 server, 615 
XF86_Accel, 614-623 
bugs, 623 
configuration, 615-616 
files, 622 
options, 616 
setup, 616-622 
XF86_AGX server, 615 
XF86_Mach32 server, 615 
XF86_Mach64 server, 615 
XF86_Mach8 server, 615 
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configuration, 624 
files, 626 
options, 624 
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XF86_P9000 server, 615 
XF86_S3 server, 615 
XF86_SVGA, 627-631 
configuration, 627-628 
files, 630-631 
options, 628 
setup, 628-630 
XF86_VGA16, 631-633 
configuration, 631 
files, 633 
options, 632 
setup, 632 
XF86_W32 server, 615 
XF86Config, 1201-1208 
Device sections, 1204-1206 
Files section, 1201 
Keyboard section, 1202 
M onitor sections, 
1203-1204 
Pointer section, 1202-1203 
Screen sections, 1206-1208 
ServerF lags section, 1201 
xf86config, 633 
xfd, 633-636 
application-specific 
resources, 635 
bugs, 636 
fontgrid resources, 635 
options, 634 
widgets, 634-635 
XFree86, 636-641 
configuration, 636 
configuration file, 
1201-1208 
D evicesections 1204- 
1206 
Files section, 1201 
Keyboard section, 1202 
M onitor sections, 
1203-1204 
Pointer section, 
1202-1203 
Screen sections, 
1206-1208 
Saver lags section, 1201 
environment variables, 637 
key combinations, 638 
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network connections, 
636-637 
options, 637-638 
setup, 638 
video mode tuner, 719-720 
buttons, 719 
moving display, 719 
options, 720 
xfs, 641-643 
bugs, 643 
configuration, 642 
naming, 643 
options, 641 
signals, 641 
xhost, 643-645 
bugs, 644 
diagnostics, 644 
environment, 644 
files, 644 
names, 644 
options, 643-644 
xiafs filesystem, 1125 
XIE protocol, testing, 
645-654 
xieperf, 645-654 
bugs, 654 
options, 646-654 
XIM files, converting to 
portable pixmaps, 654 
ximtoppm, 654 
xinetd, 655-664 
bugs, 664 
configuration file, 656-660 
editing signal responses, 
660-661 
files, 663 
internal services, 660 
log format, 661-663 
options, 655-656 
xinit, 664-666 
environment variables, 666 
examples, 665-666 
files, 666 
xkill, 666-667 
xlogo, 667-668 
environment variables, 668 
resources, 668 
widgets, 668 
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xlsatoms, 668-669 
xIsclients, 669-670 
xlsfonts, 670-671 
xmag, 671-672 
xmkmf, 672 
xmodmap, 672-676 
bugs, 675 
environment, 675 
examples, 674-675 
expression grammar, 
673-674 
options, 673 
xon, 676 
xpmtoppm, 677 
xprop, 677-681 
constructing formats, 679 
environment, 680 
examples, 680 
format characters, 679 
options, 677-678 
selecting windows, 678 
xrdb, 681-684 
bugs, 684 
environment, 684 
file symbols, 681-682 
options, 682-684 
xrefresh, 684-685 
arguments, 684-685 
bugs, 685 
defaults, 685 
environment, 685 
Xresources file, 608 
Xserver, 685-690 
file utility, 587-592 
files, 690 
fonts, 689 
options, 686-687 
neawork connections 688 
server- dependent, 
687-688 
XDMCP, 688 
XKEYBOARD, 688 
security, 688-689 
signals, 689 
starting, 685 


xset, 690-693 
xsetroot, 693-694 
xsm, 694-698 
default startup applications, 
695 


options, 695-698 
proxy, 698 
remote applications, 698 
Session menu, 695-696 
SM_SAVE_DIR environ- 
ment variable, 695 
starting sessions, 695 
tester, 698-699 
.xsession file, 695 
xsmclient, 698-699 
xstdcmap, 699-700 
xterm, 700-717 
actions, 713-716 
allow-send-eventy ), 714 
bal( ), 713 
Ccear-saved-lines ), 715 
hard-reset( ), 715 
ignore ), 713 
insert( ), 713 
insrt-aight-bit( ), 713 
insert-sdection( ), 713 
insert-seven-bit( ), 713 
keymap( ), 713 
popup-menu( ), 713 
quit( ), 714 
redraw( ), 714 
groll-back( ), 714 
groll-forw( ), 714 
secure ), 713 
slect-cursor-end, 714 
slect-cursor-sart( ), 714 
glect-end( ), 714 
slect-extend( ), 714 
glect-tart( ), 714 
gnd-gsgnal( ), 714 
gt-allow132(), 715 
gt-altscreen( ), 715 
gt-appcursor( ), 715 
st-appkeypad( ), 715 


gt-autolinefeed( ), 715 
gt-autowrap( ), 715 
set-cursesemul( ), 715 
gt-jumpscroll(), 715 
gt-marginbel( ), 715 
gt-reverse-video( ), 715 
st-reversewrap( ), 715 
xt-scroll-on-key( ), 715 
st-scroll-on-tty-output( ), 
715 
gt-scrollbar( ), 715 
get-tek-text(), 715 
gt-terminal-type{ ), 715 
gt-visbility( ), 715 
gt-visual-bdl( ), 715 
gt-vt-font( ), 714 
soft-reset( ), 715 
gart-cursor-extend( ), 714 
gart-extend( ), 714 
gring( ), 714 
tek-copy( ), 716 
tek-page ), 715 
tek-reset( ), 716 
visual-ball( ), 716 
bugs, 717 
character classes, 712-713 
emulations, 700 
environment, 717 
features, 700-701 
menus, 711-712 
options, 701-705 
pointer usage, 710-711 
resources, 705-710 
fontM enu entries 710 
mainM enu entries, 709 
tekM enu entries 710 
vtM enu entries, 709-710 
security, 712 
XV thumbnail pictures, 
converting to portable 
pixmaps, 720 
Xvfb, 717-718 
xvidtune, 719-720 
xvminitoppm, 720 





xwd, 721-722 
xwdtopnm, 722 
xwininfo, 722-724 
xwud, 725-726 
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y0( ) function, 959 
y1( ) function, 959 
ybmtopbm, 726 
yn( ) function, 959 
ytalk, 727-730 
Boolean options, 729 
daemons, 727 
escape menu, 728 
files, 730 
readdressing, 729 
runtime options, 728-729 
startup file. 729 
username field, 727 
X11 interface, 730 
YUV bytes, converting to 
portable pixmaps, 731 
YUV files, converting to 
portable pixmaps, 730-731 
yuvplittoppm, 730-731 
yuvtoppm, 731 
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z command (telnet), 512 
Z files, recompressing to GZ, 
734-735 
zcat, 248-249 
ge ald gzip 
zcatgzip, 248-249 
se ald gzip 
zcmp, 731-732 
zdiff, 731-732 
zdump, 1419 
Zeiss confocal files, converting 
to portable anymaps, 732 
zeisstopnm, 732 
zero, 1094 
zforce, 732-733 
zgrep, 733 


znew 


zic, 1419-1422 
files, 1422 
link lines, 1421-1422 
options, 1419-1420 
rule lines, 1420-1421 
zone lines, 1421 
zmore, 733-734 
znew, 734-735 
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